XDS-FAQ
More FAQ Entries - older material, the original page grew too large to continue there
How should an image and report be linked in XDS-I?
There is no specification covering this in either the XDS or XDS-I profile. A suggestion would be to use the APND association type. Its rough semantic from HL7 CDA is to link additional information. In this case the report is additional information regarding the image. This would be coded as:
- sourceObject: report
- targetObject: image
- associationType: APND
If a Document Source submits a Provide and Register transaction to a Document Repository which contains different metadata but the same hash, size, uniqueID and document as a previous P&R, what will the Document Respository do?
The repository would forward the metadata to the registry. It could store a second copy of the document or have both XDSDocumentEntry objects in registry point to the same document in the repository. The profile does not restrict this behavior.
WSDL produced by the Public Registry
It is normal in a web services environment to retrieve the WSDL for a service via http://EndpointURL?wsdl. This does not yet work on the Public Registry. This implementation is based on Axis2 and the documentation for managing/producing WSDL is almost non-existent. I have not yet found a way to have it produce the correct WSDL on the interface.
Second, for testing purposes I have to assign an EndPoint for each test. I'm not sure how this interacts with the WSDL. This may improve in the future.
Xdstest2 produces Unable to engage module : addressing error
The error
AxisFault thrown: Unable to engage module : addressing
means that the file, part of the xdstest2tool package, mar/addressing-1.3.mar is not in the classpath.
Use of base64 encoding in XDS.a
The use of base64 encoding in XDS.a has been poorly understood for a long time. After a review of relevant standards we have found that the relevant standards clearly specify what is acceptable.
- Base 64 encoding IS appropriate (may be generated by the Document Source, must be accepted by the Document Repository) for the Provide and Register transaction
- Base 64 encoding IS NOT allowed in the Retrieve Document (HTTP GET) transaction.
The Provide and Register Document Set and Retrieve Document transactions will be updated with this clarification.
When is PartialSuccess a valid status of a RegistryResponse?
This status is not used by the XDS Profile. The XDS transactions are also used by the Cross-Community Access (XCA) profile which does define its use for when results are returned from multiple communities, some successful and some not. Some have interpreted the use of PartialSuccess as a response when extra metadata is provide in a Provide and Register or Register transaction. The correct error code for this condition is XDSExtraMetadataNotSaved. A change proposal has been submitted to clarify the usage.
What does "The server failed to process the WS-Addressing header: wsa:Action [Reason]:" mean?
This message can be produced by the Public Registry in response to any XDS.b transaction. XDS.b expects WS-Addression headers in the SOAP Header. One of them is the Action header. It must be filled in and must match the value specified in XDS.b. If it is missing or not the correct value, this message will be generated by Axis2.
Can a Deprecated Document be replaced or amended, or transformed?
No. Documents (actually any object) with status of Deprecated cannot have new Associations created that reference them. The section from ebRS 2.1 that governs this is section 5.4, The Deprecate Objects Protocol:
Is it legal for the Document Source to fill in size, hash, URI attributes?
Yes. A Document Repository must fill in these 3 attributes. If they are included in a Provide and Register transaction then the Document Repository must replace their values with ones it computes. This may not make much sense thinking about only XDS. But when you consider XDR and XDM it does. The Document Source may not actually be the author of the metadata. It may have been received from another actor/system and the n forwarded to you as Repository. Even if those values are incorrect, the Document Repository must replace them with correct values.
What is the difference between XDS, XDS.a, and XDS.b?
This season we created a new XDS profile that brings XDS up to date with respect to Web Services and the Registry standard. We seriously struggled to create a naming convention that would be clear to all readers. The goals were to be able to differentiate between the old XDS and the new version of XDS AND still have a term that referred to the general idea of XDS. Basically, how to arrange the names so that both the business/marketing folks understand that we are simply growing XDS and at the same time have the technical people follow the details so there codes can follow the profile details. The result is the following usage of the XDS name:
XDS now refers to both XDS.a and XDS.b ( a family of profiles )
XDS.a is what you thought of as XDS last year.
XDS.b is a new profile which introduces:
- Updated web services including the use of WS-Addressing
- Updated Registry standard (ebRIM and ebRS 3.0)
- Use of MTOM in the Provide and Register transaction (and in the new WS Retrieve transaction as well)
- WS Retrieve - a full web services document retrieve to replace HTTP GET which uses MTOM and is capable of retrieving multiple documents in a single request
With XDS.b you loose the following capabilities from XDS.a:
- SQL query (remember that SQL query is optional in XDS.a Registry implementations)
- Retrieve via HTTP Get
- Use of SOAP with Attachments
Vendors can now choose to support the existing XDS.a or the newer XDS.b or both.
How does the XDS.b change registry metadata?
The ebRIM 3.0 specification that is referenced by XDS.b does introduce some new XML encoding. But, no new information is introduced so it is possible to translate between the versions. Some of the differences are:
- Many attributes like status, associationType, objectType have namespaces
- Classifications and ExternalIdentifiers must have id attributes
- ObjectRefs are optional
- LeafRegistryObjectList is replaced by RegistryObjectList
Should I implement XDS.a or XDS.b?
My suggestion is that infrastructure providers (Repository and Registry) offer both interfaces (they are not really that different) and clients (Source and Consumer) use XDS.b if they can an XDS.a if they need to.
How do you set up Tomcat as a Secure Node?
This is documented in this wiki here.
Problems with Base 64 encoding on submissions
Apparently it is easy, using common tools, to generate invalid Base 64 encoding. The following horrible error message is generated by the Public Registry:
xdsRepSubmit.jsp: javax.servlet.jsp.JspException: An error occurred while evaluating custom action attribute "value" with value "${rep.allMetadata}": An error occurred while getting property "allMetadata" from an instance of class gov.nist.registry.xds.RepositoryBean (java.lang.Exception: Exception in RepositoryBean: processExtrinsicObject. Error calcuating or adding size/hash information. Error in encoded stream)
The important part of this message is
Error calcuating or adding size/hash information. Error in encoded stream
The base64 RFC requires that encodings greater then 80 characters must be split with CRLF. The problem is in how openssl libraries are called.There are 2 different ways to generate the base64. One assumines less then 80 characters. the other way assumes splits at 80 characters.
the correct way for the CDA/XDS-SD/BPPC is to use 80 character splits.
Here are example encode/decode routines:
/*
filesize contains the inbuff size on input,
on function exit filesize contains the size of the return decoded data
*/
unsigned char *decode_base64(char *inbuff,int & filesize, bool nonewline)
{
BIO *sslout = BIO_new_mem_buf(inbuff,filesize);
BIO *b64 = BIO_new(BIO_f_base64());
if (nonewline) BIO_set_flags(b64,BIO_FLAGS_BASE64_NO_NL);
sslout= BIO_push(b64,sslout);
int estimatedsize = filesize * 3/4 + 8; // this is a good calculation so remember it
// this example is deliberately using a buffer to store the output, which is then written to the output file
// i did it this way so I could see how to write to memory.
unsigned char *destination = (unsigned char*)Cmemory::alloc(estimatedsize,"base64 decoded data");
char outbuf[8192]; // we'll read 8K chunks at a time
int thisread=0; int sofar=0;
do {
thisread=BIO_read(sslout,outbuf,sizeof(outbuf));
//printf("thread=%d\n",thisread);
if (thisread>0)
{
memcpy( (destination+sofar),outbuf,thisread);
sofar+=thisread;
// if(fwrite(outbuf,thisread,1,outfile)<1)
// err(-1,"");
}
} while (thisread>0);
BIO_free(sslout);
filesize=sofar;
return destination;
}
char * encode_base64(char *input, int filesize)
{
BUF_MEM encodebuf;
encodebuf.length=0;
encodebuf.max = filesize*3;
encodebuf.data = (char*)malloc(encodebuf.max);
BIO *sslout = BIO_new(BIO_s_mem());
BIO_set_mem_buf(sslout,&encodebuf,0);
BIO *b64 = BIO_new(BIO_f_base64());
sslout = BIO_push(b64,sslout);
BIO_write(sslout,input,filesize);
BIO_flush(sslout);
BIO_free(sslout);
char *rtn = Cmemory::strdup(encodebuf.data,encodebuf.length);
free(encodebuf.data);
return rtn;
}