PR for bug bash review - Shared/convert api documentation update #542
Conversation
* first draft * add api usage content
…rces provisioned in that file are available
* add custom template info * add links
Add bicep templates for customer deployment
Add monitoring/troubleshooting/bicep deploy docs
remove accidental powershell block
There was a problem hiding this comment.
We might want to add some language around this being in preview!
There was a problem hiding this comment.
Should have clarified, this page's content was meant to just put some content that @dustinburson can pull from for the main readme and not reflective of the final content.
But noted, this should be called out in the main readme. @dustinburson , let me know if you already have something in the works or if you need one of us to help fill this page out fully that you can use in the readme.
There was a problem hiding this comment.
We can consider adding the net new capabilities here as well-
"(1) Enhanced template customization and management
(2) Bidirectional data capabilities to interface with the source of record (converting FHIR R4 bundles back to source record data) "
There was a problem hiding this comment.
I think it would be helpful to highlight the bi-directional capability more here. Possibly under the first header "customize liquid templates".
There was a problem hiding this comment.
This is a great first pass!
If we have time and/or over a period of time as we continue refining these docs, I think it might be helpful to have a few things more spelled out - there's alot of redirect links here. An example could be possibly highlighting what the default configurations are so that when customers get into the sub-headers of authentication, template store integration, etc- they're able to figure out what the differences are.
There was a problem hiding this comment.
Added a section on default configurations in the deployment-options doc
|
|
||
| **Root Cause:** The template name or path specified in the RootTemplateName field of the request body could not be found. | ||
|
|
||
| **Troubleshooting:** Ensure that this value matches the value necessary to access the desired template. For default template requests, this should be only the template name. For example, to access the [ADT_A01](../../data/Templates/Hl7v2/ADT_A01.liquid) default template, the RootTemplateName field should be set to `ADT_A01`. For custom requests, this will be the name of the blob file containing the Liquid template in the storage account configured with the service. In the Azure portal, inspect your storage account to ensure that the provided `RootTemplateName` value matches the blob file name. Note that the `RootTemplateName` field should **not** contain the Storage Blob URI. See more information on writing valid request bodies to access custom templates in the [Use FHIR converter APIs](use-convert-web-apis) document. |
There was a problem hiding this comment.
Additional troubleshooting guidance:
- if they add a template to the storage account, they will need to restart the revision
- template names are case sensitive
- should not include the ".liquid" suffix in the template name
|
|
||
| Note: for any time when the service is running while Application Insights is disabled, you will not have access to metrics and request logs that were captured during that time. | ||
|
|
||
| **2. Security settings for the API endpoints are disabled.** |
There was a problem hiding this comment.
Should mention either here or in a separate deployment section in the troubleshooting doc that the array for security audiences needs to be of the format '["...","..."]'
There was a problem hiding this comment.
Interestingly, for me, I had to swap the quotes;
i.e. '["..."]' didn't work for me, but "['...']" worked for me.
Maybe test this out again before mentioning this in the docs.
|
|
||
| **Troubleshooting:** Examine the request body to ensure that the RootTemplateName field is present and is not null or empty. | ||
|
|
||
| #### <u>InnerError: InvalidRequestBody</u> |
There was a problem hiding this comment.
example - InputDataString is invalid JSON for a Json to Fhir request
|
|
||
| ``` | ||
| az deployment sub create --location <Location> --template-file FhirConverter-SingleAzureDeploy.bicep --parameters storageAccountName=<StorageAccountName> storageContainerName=<StorageContainerName> | ||
| ``` |
There was a problem hiding this comment.
Couple suggestions to simplify this:
- List in bullets or tabular format, the parameters supported.
- We can specify for each, the default value and the configurable values.
- We should just give the default quickstart versions here. If we list the parameters as suggested above, it will be clear what parameters to use with which value if they want to customize and avoids us having to show examples for each.
- In each of the configuration settings doc, we should specify the deployment command with the expected parameter in there.
docs/how-to-guides/troubleshoot.md
Outdated
|
|
||
| ## Top-Level Error Codes | ||
|
|
||
| This section describes likely causes for each top-level error code, likely root causes, and recommended troubleshooting steps. |
There was a problem hiding this comment.
We should also capture the following errors:
- invalid api route
- missing/invalid query parameter value for api-version
- request body not in json format - 415 unsupported media type
- auth related - no token, invalid token (incorrect audience, authority)
* update monitoring docs * addressing feedback
…edback Addressing bug bash feedback on deployment scripts
Deployment doc update
Remove added folder
…gupdates Add additional error codes
|
|
||
| **Troubleshooting:** If you have had previously successful requests with smaller templates, you can use the query under "InnerError: CancellationError" above with `latency_metric_name` set to `TemplateRenderDuration` to compare the latency of the Template Rendering step for your successful requests vs. your failed requests. If the template rendering timeout seems to be the likely cause, re-attempt the request with a smaller template. | ||
|
|
||
| ## 400 - Bad request |
There was a problem hiding this comment.
TODO: place all above errors under the appropriate error code
- Update main readme for new updated container based convert (WIP). - Fix APICollectionEamples to APICollectionSamples. - Remove no longer relevant TempleteManagementCLI.md
- Finish WIP items on README.md - Create concept documents for resource id generation and validation. - Add example using built in date filter to Filter and Tags documentation.
No description provided.