You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 8 Next »

Introduction

Data Manager, previously known as Data Upload, is WMDA's enhanced platform designed for efficient and secure data management within the global donor registry network. Renamed in early 2024, the platform's name change reflects its expanded functionality beyond simple data uploads, accommodating a growing range of data-related features.

Data Manager supports both manual and automatic data uploads, allowing registries to list donor information in the Search & Match Service. Manual uploads involve uploading encrypted XML files, while automatic uploads utilize a REST API for seamless integration between systems. Though XML is currently the primary format, support for JSON files is forthcoming, with notifications to be provided when this becomes available.

Once data is uploaded and processed, it becomes accessible to search coordinators and transplant physicians through the Search & Match Service, and is also integrated into the Match-Connect service. For those using the API, technical support is readily available to ensure smooth operation and understanding.

Data Manager is designed to meet the evolving needs of donor registries, offering robust and real-time data processing capabilities that ensure accurate and up-to-date information is always available. For more information and support, you can contact us directly by emailing support@wmda.info

This document describes the mechanism via the REST API method with curl commands.

Purpose

Upload and download files in Data Manager can be done using various mechanisms : 

This document describes the mechanism via the REST API method with curl commands.


Request credential

First time request

If you are not an API user yet, and plan to automate your file handling processed. Then please request an API credential from WMDA support team.

Update credential because of expiration

WMDA credential only available for one year currently. If your credential is expired, please send to support to request a new one. 
Currently, WMDA is implementing a new feature to let API user to request a new credential by themselves before the credential expires.

Refresh Bear Token

Using the REST API

To get more knowledge for usage of curl, we recommend member to read the doc for curl   https://ec.haxx.se/usingcurl-netrc.html. 

There are 2 steps 

Step 1: Request the credential from WMDA if you are not a API user yet. 

Step 2: Test to use the API in WMDA Data Manager.
            You can use the API doc in swagger: https://brave-forest-04a379103.azurestaticapps.net/?urls.primaryName=Data%20Manager%20Data%20Exchange%20API#/

Step 3: Implement the API.

If you are already familiar with the API  implementation, then you can skip Step 2, and test from your own implementation.


Below is an example to guide how to upload a file:

URL
SERVER URL

sandbox system: https://sandbox-datamanager-api.wmda.info

Production system: https://datamanager-api.wmda.info

URI

/api/v1/files/upload

Explanations: 

  • Please refer to the file naming convention.
    This  is stated as : For XML format: The files are marked with ION numbers ( ION-1234-D or ION-1234-C)
  • The ION number is the unique ION number of an organisation sending the file.
  • The D give the information that it is a donor file and the C give the information that it is a cord blood file
METHODPOST
Full URL path example

For donor for organization with ION-1234, the full path is as below:

https://sandbox-datamanager-api.wmda.info/api/v1/files/upload

Request form


HEADER

Authorization and Content-Type are required, the other ones are optional

AuthorizationBear Token
Content-Type

application/octet-stream (when your file < 128K)

multipart/form-data (when your file >128K)

From  , Content-Type is required. 
See our suggestion below in "Upload".

cX-Rename-If-Existstrue


SAMPLE Request

First test the connection by using the right path and fetching the metadata : it should result in a response 200 OK.

  • Look carefully at the path : here we use ion0999, that should be replaced by your ION.
  • You may notice that we add the filename to the path: depending on the library you may need to add that



Upload

Now we know the path is correct and we can do an upload using cURL: 

Below is the invalid to deploy, currently it is still available in PRODUCTION till production maintenance. But not available any more in STAGING dataupload. 

Invalid after update from Oct, 27, 2022
curl -i -X PUT -H "Authorization:Basic d21.....uZT=="   -T "./test.pgp"  'https://staging-dataupload.wmda.info/api/v2/io/ION0999/'


Below are suggestions with more secure headers:

The curl script needs update to upload in STAGING from Oct, 27th, 2022 after maintenance/update .  And the new suggested script can be used in PRODUCTION as well. So we strongly suggest API users to update, then there will be less stress after PRODUCTION update/maintenance.  
For registries use other script, please test in STAGING as well, and adjust with the Content-Type if not used before. We noticed that the uploaded file format can be binary or with info to identify it is PGP/GPG MESSAGE. And for PGP/GPG MESSAGE format, there are more solutions.

Suggestion 1:


For all the files, script as below is suggested for file larger than 128K.

Curl for linux
curl -i -X PUT -H "Authorization:Basic d21.....uZT==" -H "Content-Type: multipart/form-data" --data-binary "@/path/to/file/ION-0999-D.gpg"  "https://staging-dataupload.wmda.info/api/v2/io/ION0999/" -H "X-File-Name:ION-0999-D.gpg"

 

Curl for windows
curl -i -X PUT -H "Authorization:Basic d21.....uZT==" -H "Content-Type: multipart/form-data" --data-binary "@c:/path/to/file/ION-0999-D.gpg"  "https://staging-dataupload.wmda.info/api/v2/io/ION0999/" -H "X-File-Name:ION-0999-D.gpg"

Suggestion 2:


For files that encrypted and identified as PGP/GPG MESSAGE (open the encrypted file and you can see this info), then -F and -H options also work. -F already included "Content-Type: multipart/form-data", so no need to provide it any more.

For binary file, extra header information will be added to the content of the file when file is uploaded, and then it can not be decrypted any more, so please use suggestion 1 to upload. 

Curl for linux
curl -i -X PUT -H "Authorization:Basic d21.....uZT==" -F "file="@/path/to/file/ION-0999-D.gpg" "https://staging-dataupload.wmda.info/api/v2/io/ION0999/" -H "X-File-Name:ION-0999-D.gpg"
Curl for linux
curl -i -X PUT -H "Authorization:Basic d21.....uZT==" -F "file="@c:/path/to/file/ION-0999-D.gpg" "https://staging-dataupload.wmda.info/api/v2/io/ION0999/" -H "X-File-Name:ION-0999-D.gpg"



Download

Download reports

You may use the API also to fetch your reports . Unfortunately, it is not one line cmd, and need 2 steps. 

1.Fetch the files list and get the file names.

Use the following curl and endpoint to fetch an array with filedescriptors: url should use double quote or no quote in windows env:

curl -H "Authorization:Basic d21.....uZT==" https://staging-dataupload.wmda.info/api/v2/fs/reports-ion0999/?children=f

You will get the result in xml format, and you can get json format,  use the cmd  below:

curl -H "Authorization:Basic d21.....uZT==" https://staging-dataupload.wmda.info/api/v2/fs/reports-ion0999/?children=f&format=json

2.  Fetch all the reports or the one you need.

Note, you need to use "io" instead of "fs" in the path.

curl -O GET -H "Authorization:Basic d21.....uZT==" 'https://staging-dataupload.wmda.info/api/v2/io/reports-ion0999/$filename' -o '$filename.txt'

In windows cmd, the -o dose not work, and the cmd is as below:

curl -H "Authorization:Basic d21.....uZT==" https://staging-dataupload.wmda.info/api/v2/io/reports-ion0999/$filename > $filename.txt

Download archived files

Download archived files will be the same as download reports. And 2 steps as above are needed.

The example URL for archive folder is as below:

https://staging-dataupload.wmda.info/api/v2/fs/archive-ion0999/?children=f


In RESTLET :


                       

Click on Code to get raw CURL syntax:


Response should be 200:


Download full dataset

For those registries that are permitted to use the full dataset the statement below will fetch that. Please change the ION workspace to match your ION.

curl -O GET -H "Authorization:Basic .............." 'https://dataupload.wmda.info/api/v2/io/downloads/ION1804/bmdw4data.zip.gpg' -o 'wmda_data_v22.zip.gpg'

In windows cmd, the -o dose not work, and the cmd is as below:

curl -H "Authorization:Basic .............." "https://dataupload.wmda.info/api/v2/io/downloads/ION1804/bmdw4data.zip.gpg" > wmda_data_v22.zip.gpg


We noticed sometimes the download maybe terminated because of some temp network limitation, and the "-C -" option can be used to continue the download.
-v is for more details of the track info

curl -v -H "Authorization:Basic .............." -o 'wmda_data_v22.zip.gpg' -C - 'https://dataupload.wmda.info/api/v2/io/downloads/ION1804/wmda_data_v22.zip.gpg'


FAQ


Question : My report states : File could not be processed due to a file decryption error, when using the API upload? Why?

Answer :

The Dataupload's API endpoint /io streams file(s) directly to the workspace. We have detected that premature file pickups may occur and attempt to move/delete files while content is still being appended or processed. We have taken actions to reduce this behaviour by decreasing the frequency for file pickup which in turn does lower the chance for premature pick. We have also implemented gpg error validation to check integrity based on its messages.

Note: Files are picked from the workspaces for processing every 10 minutes. And file will only picked up if it is not updated for 5 mins.

Some key messages:

  • Known internal gpg messages for corrupted files during API uploads: "invalid packet", "invalid encoding" and "failed". 
  • Report message that uploader users would receive in case of corrupted gpg file upload:   File could not be processed due to a file decryption error. Please make sure file is properly encrypted. 

For more information please contact WMDA support team.


  • No labels