Version: 1.x

Envelope file format

Envelopes are used to pass data to the LinXmart data linkage system, with specific information that describes what the data is and what LinXmart should do with it.

This Envelope file is also used to pass data back to the user. For example, the results of a probability estimation and the results of a linkage map extraction are both in the format of an Envelope.

The Envelope data file format is a zip file. Within this zip file are three types of files:

1 Manifest file
1 or more Data files
0 or more Metadata files

Manifest

The manifest file is an XML file that contains the information that describes what type of Envelope it is, what it is for, and describes all of the data and metadata files that sit alongside it.

The name of the manifest file must be manifest.xml and basic structure of the manifest file is as follows:

manifest.xml
<?xml version="1.0" encoding="utf-8"?>
<Manifest xmlns="http://www.phrn.org.au/participants/cdl/20110801">
    <LinkageProject>[linkage project code]</LinkageProject>
    <Sender>[data provider code]</Sender>
    <RequestType>[data action]</RequestType>
    <NumberOfDataFiles>1</NumberOfDataFiles>
    <Data>
        <File fileName="data.csv" format="FlatFile" datasource="[event type code]" />
    </Data>
    <Metadata>
      <File fileName="sourcefields.csv" description="Source Field Statistics" />
      <File fileName="systeminfo.txt" description="System Information and Baseline" />
      <File fileName="envelope.json" description="Simple Envelope Definition" />
      <File fileName="project.json" description="Project Definition" />
    </Metadata>
</Manifest>

The placeholder values in braces ([]) above must reflect the correct values in the system, otherwise the validation of the Envelope will fail. As you can see, an Envelope applies to a single Data Provider, but each data file can apply to a separate Event Type within that Data Provider.

The [data action] can be one of the following values:

Data Action	Notes
SubmitLinkage	The data files are loaded for linkage. All files are loaded before matching and grouping occurs.
ProbabilityCalculation	The data files are run through a probability estimation process.
Delete	The data files contain record IDs to be deleted.
QualityReview	The data files contain update groupings of existing records.
ExtractMapping	The data files contain record IDs to extract the linkage map for. This also requires an additional element `<ExtractionProjectId>` that should contain the system generated ID of the Extraction Project to use for the extraction process.

Data files

All data files are expected to be in a plain text format. The exact format of these will differ depending on the data action specified and the data sources configured in the system.

Metadata files

The metadata files are not used by the LinXmart application and are more information for the user. They are not required and are only typically created and used by the Simple Envelope Builder.

Examples

Any identifying data used in the following examples are synthetically generated and do not represent real individuals.

Basic linkage request

basic-linkage-request.zip
manifest.xml
data.csv

manifest.xml
<?xml version="1.0" encoding="utf-8"?>
<Manifest xmlns="http://www.phrn.org.au/participants/cdl/20110801">
    <LinkageProject>TUTORIAL</LinkageProject>
    <Sender>WA-HEALTH</Sender>
    <RequestType>SubmitLinkage</RequestType>
    <NumberOfDataFiles>1</NumberOfDataFiles>
    <Data>
        <File fileName="data.csv" format="FlatFile" datasource="WA-BIRTHS" />
    </Data>
</Manifest>

data.csv
Record Id,Given Name,Middle Name,Family Name,Date Of Birth,Sex,Address,Suburb,Postcode,State
2002274718,JUDITH,KAYE,COLMER,19990107,F,14 DESERT ASH PLACE,HELENA VALLEY,6056,5
1000244830,LAUREHCE,,BANAVAD,19691103,M,GARDEN CITY SHOPPING CENTRE 99 SHOP 125 133 RISELEY STREET,BOORAGOON,6154,5
1000666061,STUART,LEIGH,VERONN,20041107,M,6 UNIT 4 AIRLIE STREET,CLAREMONT,6010,5
1001124074,BRYCE,,MATTHRWS,19470623,M,11 BEVAN LOOP,ROELANDS,6226,5
2000461216,JULIETTE,,BULLEN,19850717,F,16 NEEDLEWOOD RISE,KENWICK,6107,5

Multi file linkage request

multi-file-linkage-request.zip
manifest.xml
data-births.csv
data-hospital.csv

manifest.xml
<?xml version="1.0" encoding="utf-8"?>
<Manifest xmlns="http://www.phrn.org.au/participants/cdl/20110801">
    <LinkageProject>TUTORIAL</LinkageProject>
    <Sender>WA-HEALTH</Sender>
    <RequestType>SubmitLinkage</RequestType>
    <NumberOfDataFiles>2</NumberOfDataFiles>
    <Data>
        <File fileName="data-births.csv" format="FlatFile" datasource="WA-BIRTHS" />
        <File fileName="data-hospital.csv" format="FlatFile" datasource="WA-HOSP" />
    </Data>
</Manifest>

data-births.csv
Record Id,Given Name,Middle Name,Family Name,Date Of Birth,Sex,Address,Suburb,Postcode,State
2002274718,JUDITH,KAYE,COLMER,19990107,F,14 DESERT ASH PLACE,HELENA VALLEY,6056,5
1000244830,LAUREHCE,,BANAVAD,19691103,M,GARDEN CITY SHOPPING CENTRE 99 SHOP 125 133 RISELEY STREET,BOORAGOON,6154,5
1000666061,STUART,LEIGH,VERONN,20041107,M,6 UNIT 4 AIRLIE STREET,CLAREMONT,6010,5
1001124074,BRYCE,,MATTHRWS,19470623,M,11 BEVAN LOOP,ROELANDS,6226,5
2000461216,JULIETTE,,BULLEN,19850717,F,16 NEEDLEWOOD RISE,KENWICK,6107,5

data-hospital.csv
Record Id,Given Name,Middle Name,Family Name,Date Of Birth,Sex,Address,Suburb,Postcode,State
1002735183,ALAN,,KNOTT,,M,3 BOYD CLOSE,SOUTH GUILDFORD,6055,5
2000611041,SARAH,ROSE,MCCLURE,19961126,F,16 UNIT 431 BAGOT ROAD,SUBIACO,6008,5
2001366752,JULIE,LYNN,NGUYEM,19650413,F,6549 GREAT NORTHERN HI GHWAY,BINDOON,6502,5
2000604937,ANITA,ANN,WANSTALL,20031212,F,27 BALLIOL COURT,PIARA WATERS,6112,5
1001074689,JAKE,MARIAN,WONG,19820530,M,213 LONG STREET,MOORA,6510,5

Deletion request

deletion-request.zip
manifest.xml
data.csv

manifest.xml
<?xml version="1.0" encoding="utf-8"?>
<Manifest xmlns="http://www.phrn.org.au/participants/cdl/20110801">
    <LinkageProject>TUTORIAL</LinkageProject>
    <Sender>WA-HEALTH</Sender>
    <RequestType>Delete</RequestType>
    <NumberOfDataFiles>1</NumberOfDataFiles>
    <Data>
        <File fileName="data.csv" format="FlatFile" datasource="WA-BIRTHS" />
    </Data>
</Manifest>

Probability estimation request

prob-est-request.zip
manifest.xml
data.csv

manifest.xml
<?xml version="1.0" encoding="utf-8"?>
<Manifest xmlns="http://www.phrn.org.au/participants/cdl/20110801">
    <LinkageProject>TUTORIAL</LinkageProject>
    <Sender>WA-HEALTH</Sender>
    <RequestType>ProbabilityCalculation</RequestType>
    <NumberOfDataFiles>1</NumberOfDataFiles>
    <Data>
        <File fileName="data.csv" format="FlatFile" datasource="WA-BIRTHS" />
    </Data>
</Manifest>

data.csv
Record Id,Given Name,Middle Name,Family Name,Date Of Birth,Sex,Address,Suburb,Postcode,State
2002274718,JUDITH,KAYE,COLMER,19990107,F,14 DESERT ASH PLACE,HELENA VALLEY,6056,5
1000244830,LAUREHCE,,BANAVAD,19691103,M,GARDEN CITY SHOPPING CENTRE 99 SHOP 125 133 RISELEY STREET,BOORAGOON,6154,5
1000666061,STUART,LEIGH,VERONN,20041107,M,6 UNIT 4 AIRLIE STREET,CLAREMONT,6010,5
1001124074,BRYCE,,MATTHRWS,19470623,M,11 BEVAN LOOP,ROELANDS,6226,5
2000461216,JULIETTE,,BULLEN,19850717,F,16 NEEDLEWOOD RISE,KENWICK,6107,5

Batch quality review request

quality-review-request.zip
manifest.xml
data.csv

manifest.xml
<?xml version="1.0" encoding="utf-8"?>
<Manifest xmlns="http://www.phrn.org.au/participants/cdl/20110801">
    <LinkageProject>TUTORIAL</LinkageProject>
    <RequestType>QualityReview</RequestType>
    <NumberOfDataFiles>1</NumberOfDataFiles>
    <Data>
        <File fileName="data.csv" format="FlatFile" />
    </Data>
</Manifest>

data.csv
TUTORIAL,b0001,WA-BIRTHS,1
TUTORIAL,h1001,WA_HOSP,1
TUTORIAL,h1002,WA_HOSP,1
TUTORIAL,b0002,WA-BIRTHS,2
TUTORIAL,h1010,WA_HOSP,2
TUTORIAL,h1011,WA_HOSP,2

Extract mapping request

extraction-request.zip
manifest.xml
data.csv

manifest.xml
<?xml version="1.0" encoding="utf-8"?>
<Manifest xmlns="http://www.phrn.org.au/participants/cdl/20110801">
    <LinkageProject>TUTORIAL</LinkageProject>
    <Sender>WA-HEALTH</Sender>
    <RequestType>ExtractMapping</RequestType>
    <ExtractionProjectId>LXM2023110038</ExtractionProjectId>
    <NumberOfDataFiles>1</NumberOfDataFiles>
    <Data>
        <File fileName="data.csv" format="FlatFile" datasource="WA-BIRTHS" />
    </Data>
</Manifest>

Manifest​

Data files​

Metadata files​

Examples​

Basic linkage request​

Multi file linkage request​

Deletion request​

Probability estimation request​

Batch quality review request​

Extract mapping request​