(NEW) 1. End-to-End process to submit data (merged tables only)

(NEW) 1. End-to-End process to submit data (merged tables only)

Last updated: 2024-10-01 13:21

merged tables from

API endpoint overview

The baseURL to be used has to following built: https://<hd4dp_url>/proxy

API endpointResponsAuthenticationNotes
{{baseURL}}/api/organizations



List of organizations.
Client must select the right organizationId

Current existing end-point is: /api/installation/organizations

We’ll create this new end-point with a different signature re-routing the call to this existing one or we will refactor the existing one to this new signature.
{{baseURL}}/api/externalreference/sadmi?notificationCode={notificationCode};

<optional> name={name};
<optional> reference={reference};
<optional> distributorName={distributorName};
<optional> manufacturerName={manufacturerName};
<optional> classificationCode={classificationCode}



List of Medical Device
Types:
- NotificationCode
- Name
- Reference URL
- Distributor
- Manufacturer
- Classification
- State

Client must select the desired information.
{{baseURL}}/api/dcd/submit?organization-id={organizationtId};

<optional> dcd-id={dcd-id};
<optional> dcd-version-id={dcdVersionId};
<optional> incl-submit-data={inclSubmitData};
<optional> incl-submit-results={inclSubmitResults};


GET method

List of submitted data and/or their corresponding business keys or validation errors.







 		<optional parameter> dcd-version-id={dcdVersionId}:
If this parameter is not provided, lastest one is assumed 
 
<optional parameter> incl-submit-data={inclSubmitData}:
If this parameter is not provided, default values is <false> 
 
<optional parameter> incl-submit-results={inclSubmitResults}:
If this parameter is not provided, default values is <true>
 


{{baseURL}}/api/dcd/payload/submit?organization-id=organizationId};

<optional> dcd-id={dcdId};
<optional> dcd-version-id={dcdVersionId};
<optional> data-src-type={dataSrcType}; 
 

POST Payload





Results info if succeed
Error info if failed












  		Some implementation tasks are needed here in order to return the result info (either succeed or failed).  
Similar like the one in HDConnectProxyRestTemplate.postCsv method, and the CsvExecutionResult object build.
 
<optional parameter> dcd-version-id={dcdVersionId}: If this parameter is not provided, latest one is assumed. 
 
<optional parameter> data-src-type={dataSrcType} :  
permitted values:  
- API 
- CSV 

If this parameter is not provided, default values is <HD4DP>.
{{baseURL}}/api/dcd/payload/submit?organization-id={organizationtId};

<optional> dcd-id={dcd-id};
<optional> dcd-version-id={dcdVersionId};<optional> incl-submit-data={inclSubmitData}; <optional> incl-submit-results={inclSubmitResults}; 


GET method
List of submitted data and/or their corresponding business keys or validation errors.







<optional parameter> dcd-version-id={dcdVersionId}:
If this parameter is not provided, lastest one is assumed  

<optional parameter> incl-submit-data={inclSubmitData}:
If this parameter is not provided, default values is <false>

<optional parameter> incl-submit-results={inclSubmitResults}:
If this parameter is not provided, default values is <true>



{{baseURL}}/api/dcd/payload/example?dcd-id={dcdId};

<optional> version={version}

Example of payload in JSON format



Providing this API end-point in order to help the Client on the Payload build with an example
 
<optional parameter> version={version}:
If this parameter is not provided, latest one is assumed 
{{baseURL}}/api/dcd/payload/definition?dcd-id={dcdId};

<optional> version={version};
<optional> language-id={languageId}




















List of all the fields of the form as well as their corresponding data-types that are allowed in the json data structure for the Payload  



















This field names values are the key properties in the formIO json config form. When we implement this new api end-point, we need to parse the json content in order to get the key properties. Given these field keys, we’ll get each field definition from new API end-points helpers:

/api/dcd/field?field-id={fieldId} 
/api/dcd/codelist?codelist-id={codelistId} 

These ones are described in the next table. 

<optional parameter> version = {version}:
If this parameter is not provided, latest one is assumed 

<optional parameter> language-id = {languageId}:
language id for the code_list example results.
If this parameter is not provided, default language will be English.

Current permitted values: 

en: English 
nl: Dutch 
fr: French 

Client must build this json object as the payload data to be sent based on this list of fields, on the last api call
{{baseURL}}/api/dcd/menu/structure?organization-id={organizationId}






List of projects of the given organization, dcds of each project, dcdVersions of each dcd in a JSON format
Client can get dcdId and dcdVersionId (optional) which are needed on following API calls. 
https://github.com/Sciensano-Healthdata/hd4-formio/blob/develop/dev/mock_menu_structure/menu-structure.json  






{{baseURL}}/api/dcd/field?dcd-id={dcdId};

<optional> dcd-version-id={dcdVersionId};
<optional> included-codelist-values={inclCodelistValues};
<optional> field-name={fieldname};
<optional> language-id={languageId}
List of DCD fields definition, even with codelist values if the field is CODE field type.




  		<optional parameter> dcd-version-id={dcdVersionId}:
If this parameter is not provided, latest one is assumed

<optional parameter> included-codelist-values={inclCodelistValues}:
permitted values:
- true
- false
If this parameter is not provided, default value is <true>

<optional parameter> field-name={fieldname}:
A field name e.g: TX_AUTHOR_GR

<optional parameter> language-id={languageId}:
language id for the code_list example results
If this parameter is not provided, default language will be English. Current permitted values:
- en: English
- nl: Dutch
- fr: French 
{{baseURL}}/api/dcd/field/translation?dcd-id={dcdId};

<optional> dcd-version-id={dcdVersionId};
<optional> language-id={languageId};
<optional> field-name={fieldName}







List of fields translations for a  given dcdId in the specified languageId (English if it is not provided) in a JSON format. Optional fieldId parameter can be provided just for getting this info but only for this fieldId.







<optional parameter> dcd-version-id={dcdVersionId}:
If this parameter is not provided, lastest one is assumed

<optional parameter>  language-id={languageId}:
language id for the code_list example results.
If this parameter is not provided, default language will be English.
Current permitted values:
- en: English
-nl: Dutch
- fr: French

<optional parameter> field-name={fieldName}:
A field name e.g: TX_AUTHOR_GR
{{baseURL}}/api/dcd/codelist?code-list-id={codelistId};

<optional>language={language}


List of values for the codelist of the given codelistId.(List<CodeListItem>)  



Checking and getting this info based on MDM -> CODE_LIST table and the relationed  tables (CODE, CODE_CONTENT etc.)
See MDM – Field description – DB model diagram at the Attachment chapter for more details.

<optional parameter> language-id={languageId}:
language id for the code_list example results.
If this parameter is not provided, default language will be English.
Current permitted values:
- en: English
- nl: Dutch
- fr: French

Get organizations

Request example  

GET {{baseURL}}/api/organizations 

Request response 

[ 

   { 

      "organizationId": 1, 

      "organizationCode":"12345", 

      "name":"First Organization Name", 

      "loginMethods":[ 

         "USERNAME_PASSWORD", 

         "EID" 

      ] 

   }, 

   { 

      "organizationId": 2, 

      "organizationCode":"32154", 

      "name":"Second Organization Name", 

      "loginMethods":[ 

         "EID" 

      ] 

   } 

] 

Get the DCD menu structure 

Request example  

GET {{baseURL}}/api/dcd/menu/structure?organization-id={organizationId} 

Request parameters 

  • {organizationtId}: Id of the organization as provided by Healthdata.be and for which we want to list the menu structure 
  • {{baseURL}}: the value for this field is https://<hd4dp_url>/proxy

Request response 

All the menu structure for that organization, including projects, dcds of each project and dcd versions of each dcd, in a JSON format.

[ 

  { 

    "id": 4, 

    "key": "zephyr_pneumo_program", 

    "projects": [ 

      { 

      "id": 4, 

      "key": "zephyr_pneumo_project", 

      "dcds": [{ 

          "id": 9, 

          "key": "zephyr_pneumo_t1_dcd", 

          "dcdVersions": [{ 

            "id": 9, 

            "version": 1, 

            "supportsEN": false, 

            "supportsFR": true, 

            "supportsNL": true 

          }] 

        }, 

        { 

          "id": 10, 

          "key": "zephyr_pneumo_tr_dcd", 

          "dcdVersions": [{ 

            "id": 10, 

            "version": 1, 

            "supportsEN": false, 

            "supportsFR": true, 

            "supportsNL": true 

          }] 

        }, 

. . .  

. . .  

. . .  

. . .  

] 

Get DCD field definitions 

Request example  

GET {{baseURL}}/api/dcd/payload/definition?dcd-id={dcdId};version={version};language-id={languagerId} 

Request parameters 

  • {dcdId}: Id of the dcd 
  • <optional parameter> {version}: If this parameter is not provided, latest one is assumed
  • <optional parameter> {languageId}: language id for the code_list example results. If this parameter is not provided, default language will be English. Current permitted values: 
    • en: English
    • nl: Dutch
    • fr: French

Request response 

{ 

   "CD_SURGL_APPR_FEMO": { 

    "field_type": "CODE", 

    "data_type": "number", 

    "code_list": [ 

      { 

            "ID": 68224, 

        "CODE_VALUE": "870646003", 

        "LABEL_EN": "Femoral (Hemi)" 

      }, 

      { 

        "ID": 68225, 

        "CODE_VALUE": "465954006", 

        "LABEL_EN": "Femoral + Cup" 

      } 

    ] 

  },  

  "D_IMPLANT": { 

    "field_type": "DATE", 

    "data_type": "timestamp", 

    "code_list": null 

  }, 

  "TX_TPE_INSTRU": { 

    "field_type": "FREE TEXT", 

    "data_type": "string", 

    "code_list": null 

  }, 

  "MS_PAT_HGHT": { 

    "field_type": "FREE TEXT", 

    "data_type": "number", 

    "code_list": null 

  } 

} 

Get DCD payload example

Request example  

GET {{baseURL}}/api/dcd/payload/example?dcd-id={dcdId};version={version} 

Request parameters 

  • {dcdId}: Id of the dcd 
  • <optional parameter> {version}: If this parameter is not provided, latest one is assumed

Request response 

Given the previous Payload field definition example on previous chapter, we build a payload content example accordingly.

{ 

   "CD_SURGL_APPR_FEMO": 68224, 

   "D_IMPLANT": "2021-04-30T22:00:00", 

   "TX_TPE_INSTRU": "P-432", 

   "MS_PAT_HGHT": 180 

} 

Submit DCD registrations

Request example  

POST {{baseURL}}/api/dcd/payload/submit?organization-id={organizationId};dcd-id={dcdId};dcd-version-id={dcdVersionId};data-src-type={dataSrcType} 

Header: 

   MediaType.APPLICATION_JSON 

Body: 

{ 

   { 

      "CD_SURGL_APPR_FEMO": 68224, 

      "D_IMPLANT": "2021-04-30T22:00:00", 

      "TX_TPE_INSTRU": "P-432", 

      "MS_PAT_HGHT": 180 

   }, 

   { 

      "CD_SURGL_APPR_FEMO": 68225, 

      "D_IMPLANT": "2021-04-14T22:00:00", 

      "TX_TPE_INSTRU": "P-545", 

      "MS_PAT_HGHT": 1209 

   }, 

   { 

      "CD_SURGL_APPR_FEMO": 68224, 

      "D_IMPLANT": "2021-05-01T22:00:00", 

      "TX_TPE_INSTRU": "T-678", 

      "MS_PAT_HGHT": 210 

   } 

} 

Request parameters 

  • {organizationtId}: Id of the organization for which we want to submit the DCD registration.
  • {dcdId}: Id of the DCD we want to submit.
  • <optional parameter> {dcdVersionId}: Id of the DCD Version we want to submit. If this parameter is not provided, latest one is assumed.  
  • <optional parameter> {dataSrcType}: The data source type e.g: API or CSV. 

Request payload 

  • {Header}: MediaType.APPLICATION_JSON 
  • {Body}: JSON object with an array of DCDs data to be submitted, following the specifications and examples provided by the described api end-points: 
  • GET /api/dcd/payload/definition 
  • GET /api/dcd/payload/example 

Request response 

Client get a response per each DCD line. If the DCD submission was successful, Client will get a TXT_BUSINESS_KEY value. If it was failed, Client will get an error detailed info: Http Status Code, Name and Exception details: 

{ 

   "TX_BUSINESS_KEY": "NISS 12.06.01-052.46 30/04/2021 67864", 

   { 

      "HTTP_STATUS_CODE": 405, 

      "HTTP_STATUS_NAME": "Method Not Allowed", 

      "HTTP_STATUS_EXCEPTION_DETAILS": "Exception details for Method Not Allowed example", 

   }, 

   "TX_BUSINESS_KEY": "NISS 12.06.01-071.48 01/05/2021 67864", 

}

User / password

The username and password can be requested at our Servicedesk.

Additional fields

In addition to this, more in depth information about the codes and the formats used for the Author group, NISS code, status, Postal Code, "Date" - "Date:Time", repeatable fields and multiple choice fields are available here.

Get organizations

Request example  

GET {{baseURL}}/api/organizations 

Request response 

[ 

   { 

      "organizationId": 1, 

      "organizationCode":"12345", 

      "name":"First Organization Name", 

      "loginMethods":[ 

         "USERNAME_PASSWORD", 

         "EID" 

      ] 

   }, 

   { 

      "organizationId": 2, 

      "organizationCode":"32154", 

      "name":"Second Organization Name", 

      "loginMethods":[ 

         "EID" 

      ] 

   } 

] 

Get the DCD menu structure 

Request example  

GET {{baseURL}}/api/dcd/menu/structure?organization-id={organizationId} 

Request parameters 

  • {organizationtId}: Id of the organization as provided by Healthdata.be and for which we want to list the menu structure 
  • {{baseURL}}: the value for this field is https://<hd4dp_url>/proxy

Request response 

All the menu structure for that organization, including projects, dcds of each project and dcd versions of each dcd, in a JSON format.

[ 

  { 

    "id": 4, 

    "key": "zephyr_pneumo_program", 

    "projects": [ 

      { 

      "id": 4, 

      "key": "zephyr_pneumo_project", 

      "dcds": [{ 

          "id": 9, 

          "key": "zephyr_pneumo_t1_dcd", 

          "dcdVersions": [{ 

            "id": 9, 

            "version": 1, 

            "supportsEN": false, 

            "supportsFR": true, 

            "supportsNL": true 

          }] 

        }, 

        { 

          "id": 10, 

          "key": "zephyr_pneumo_tr_dcd", 

          "dcdVersions": [{ 

            "id": 10, 

            "version": 1, 

            "supportsEN": false, 

            "supportsFR": true, 

            "supportsNL": true 

          }] 

        }, 

. . .  

. . .  

. . .  

. . .  

] 

Get DCD field definitions 

Request example  

GET {{baseURL}}/api/dcd/payload/definition?dcd-id={dcdId};version={version};language-id={languagerId} 

Request parameters 

  • {dcdId}: Id of the dcd 
  • <optional parameter> {version}: If this parameter is not provided, latest one is assumed
  • <optional parameter> {languageId}: language id for the code_list example results. If this parameter is not provided, default language will be English. Current permitted values: 
    • en: English
    • nl: Dutch
    • fr: French

Request response 

{ 

   "CD_SURGL_APPR_FEMO": { 

    "field_type": "CODE", 

    "data_type": "number", 

    "code_list": [ 

      { 

            "ID": 68224, 

        "CODE_VALUE": "870646003", 

        "LABEL_EN": "Femoral (Hemi)" 

      }, 

      { 

        "ID": 68225, 

        "CODE_VALUE": "465954006", 

        "LABEL_EN": "Femoral + Cup" 

      } 

    ] 

  },  

  "D_IMPLANT": { 

    "field_type": "DATE", 

    "data_type": "timestamp", 

    "code_list": null 

  }, 

  "TX_TPE_INSTRU": { 

    "field_type": "FREE TEXT", 

    "data_type": "string", 

    "code_list": null 

  }, 

  "MS_PAT_HGHT": { 

    "field_type": "FREE TEXT", 

    "data_type": "number", 

    "code_list": null 

  } 

} 

Get DCD payload example

Request example  

GET {{baseURL}}/api/dcd/payload/example?dcd-id={dcdId};version={version} 

Request parameters 

  • {dcdId}: Id of the dcd 
  • <optional parameter> {version}: If this parameter is not provided, latest one is assumed

Request response 

Given the previous Payload field definition example on previous chapter, we build a payload content example accordingly.

{ 

   "CD_SURGL_APPR_FEMO": 68224, 

   "D_IMPLANT": "2021-04-30T22:00:00", 

   "TX_TPE_INSTRU": "P-432", 

   "MS_PAT_HGHT": 180 

} 

Submit DCD registrations

Request example  

POST {{baseURL}}/api/dcd/payload/submit?organization-id={organizationId};dcd-id={dcdId};dcd-version-id={dcdVersionId};data-src-type={dataSrcType} 

Header: 

   MediaType.APPLICATION_JSON 

Body: 

{ 

   { 

      "CD_SURGL_APPR_FEMO": 68224, 

      "D_IMPLANT": "2021-04-30T22:00:00", 

      "TX_TPE_INSTRU": "P-432", 

      "MS_PAT_HGHT": 180 

   }, 

   { 

      "CD_SURGL_APPR_FEMO": 68225, 

      "D_IMPLANT": "2021-04-14T22:00:00", 

      "TX_TPE_INSTRU": "P-545", 

      "MS_PAT_HGHT": 1209 

   }, 

   { 

      "CD_SURGL_APPR_FEMO": 68224, 

      "D_IMPLANT": "2021-05-01T22:00:00", 

      "TX_TPE_INSTRU": "T-678", 

      "MS_PAT_HGHT": 210 

   } 

} 

Request parameters 

  • {organizationtId}: Id of the organization for which we want to submit the DCD registration.
  • {dcdId}: Id of the DCD we want to submit.
  • <optional parameter> {dcdVersionId}: Id of the DCD Version we want to submit. If this parameter is not provided, latest one is assumed.  
  • <optional parameter> {dataSrcType}: The data source type e.g: API or CSV. 

Request payload 

  • {Header}: MediaType.APPLICATION_JSON 
  • {Body}: JSON object with an array of DCDs data to be submitted, following the specifications and examples provided by the described api end-points: 
  • GET /api/dcd/payload/definition 
  • GET /api/dcd/payload/example 

Request response 

Client get a response per each DCD line. If the DCD submission was successful, Client will get a TXT_BUSINESS_KEY value. If it was failed, Client will get an error detailed info: Http Status Code, Name and Exception details: 

{ 

   "TX_BUSINESS_KEY": "NISS 12.06.01-052.46 30/04/2021 67864", 

   { 

      "HTTP_STATUS_CODE": 405, 

      "HTTP_STATUS_NAME": "Method Not Allowed", 

      "HTTP_STATUS_EXCEPTION_DETAILS": "Exception details for Method Not Allowed example", 

   }, 

   "TX_BUSINESS_KEY": "NISS 12.06.01-071.48 01/05/2021 67864", 

}

User / password

The username and password can be requested at our Servicedesk.

Additional fields

In addition to this, more in depth information about the codes and the formats used for the Author group, NISS code, status, Postal Code, "Date" - "Date:Time", repeatable fields and multiple choice fields are available here.

This documentation is being updated regularly. We try to provide as correct, complete and clear as possible information on these pages. Nevertheless, if you see anything in the documentation that is not correct, does not match your experience or requires further clarification, please create a support ticket via our portal (https://healthdatabe.atlassian.net/servicedesk/customer/portals) or send us an e-mail via support.healthdata@sciensano.be to report this documentation issue. Please, do not forget to mention the URL or web address of the page with the documentation issue. We will then adjust the documentation as soon as possible. Thank you!