CDR Tickets

BZDATETIME::2010-02-19 00:56:33
BZCOMMENTOR::Alan Meyer
BZCOMMENT::1

The original document I'm editing dates from 2001. I'm making significant revisions to it. I have a couple of more hours of work on it and will then upload it, perhaps next Tuesday, as an attachment to this issue.

BZDATETIME::2010-02-24 00:46:02
BZCOMMENTOR::Alan Meyer
BZCOMMENT::2

The attached document is an attempt at a user level explanation
of how linking works in the CDR. It is an extensively revised
version of a document written in 2001 and last updated in 2002.

I recommend that the first step in of this task is for one or,
better still, more than one user to read the document and see if
it appears, complete, accurate, and understandable. If there are
errors, questions, or need of clarification or elaboration,
please let me know and I'll try to edit the document to resolve
the issues.

When we think it's right, the next step is for CIAT to convert it
to XML and add it to the CDR User oriented documentation.

Attachment linksummary2.doc has been added with description: Summary of CDR Server Link Capabilities

BZDATETIME::2010-03-08 19:23:32
BZCOMMENTOR::William Osei-Poku
BZCOMMENT::3

(In reply to comment #2)
> Created an attachment (id=1868) [details]
> Summary of CDR Server Link Capabilities
> The attached document is an attempt at a user level explanation
> of how linking works in the CDR. It is an extensively revised

I have read through the document and it is well written and quite clear to me.

I have two questions:
1. On the first page, you indicated that there is no need to write or modify server software if you decided to declare an element as a link element. Why is this case?

2. In terms of validating links. Are links validated automatically in a document or you need to modify software in order to validate links?
I know of at least one situation where a cdr link element without a cdr:ref attribute passes validation. That is, when text is typed into the field (instead of actually providing a link to the target document and thus having a CDR ID in the attribute). You may take a look at CDR588868 on Mahler. The first <OrgSiteID> element is not linked to any document; I have just typed in the text and yet it passes validation, including link validation. The vendor filter eventually flags such errors but I was just wondering why it will not be flagged for validation or linking error?

BZDATETIME::2010-03-08 20:37:17
BZCOMMENTOR::Alan Meyer
BZCOMMENT::4

(In reply to comment #3)

> I have read through the document and it is well written and
> quite clear to me.

Thanks.

> I have two questions:
> 1. On the first page, you indicated that there is no need to
> write or modify server software if you decided to declare an
> element as a link element. Why is this case?

It's because, when you declare an element as a link element, a
database table is updated to tell the software to expect a link
there. The names of the link elements are in the table, not hard
coded in the software. The software reads that table to find out
what elements are links. I'll modify the document tomorrow to
explain this.

> 2. In terms of validating links. Are links validated
> automatically in a document or you need to modify software in
> order to validate links? I know of at least one situation
> where a cdr link element without a cdr:ref attribute passes
> validation. That is, when text is typed into the field (instead
> of actually providing a link to the target document and thus
> having a CDR ID in the attribute). You may take a look at
> CDR588868 on Mahler. The first <OrgSiteID> element is not
> linked to any document; I have just typed in the text and yet
> it passes validation, including link validation. The vendor
> filter eventually flags such errors but I was just wondering
> why it will not be flagged for validation or linking error?

Link validation does not test for the existence of a cdr:ref
because schema validation should already test for that.

It looks to me like there's a bug in the schema. OrgSiteID has a
cdr:ref attribute that is defined as optional. In theory, if the
link is optional, it's not a bug not to have it.

In practice however, I think that cdr:ref ought to be a required
attribute on all linking elements. I'll check with Bob and
Volker to see if there's some reason why it's not and if they
agree with me that it should be required. I presume you believe
it should be required based on your considering that the behavior
of the system is wrong on this element.

If I'm right that it ought to be required (I can't think of any
reason why a cdr:ref wouldn't be required if it's defined for an
element), I'll fix the schema. If you know of any other cases
like that, please let me know.

BZDATETIME::2010-03-09 11:52:07
BZCOMMENTOR::Alan Meyer
BZCOMMENT::5

(In reply to comment #3)
...
> I know of at least one situation where a cdr link element
> without a cdr:ref attribute passes validation. That is, when
> text is typed into the field (instead of actually providing a
> link to the target document and thus having a CDR ID in the
> attribute). You may take a look at CDR588868 on Mahler. The
> first <OrgSiteID> element is not linked to any document; I have
> just typed in the text and yet it passes validation, including
> link validation. The vendor filter eventually flags such errors
> but I was just wondering why it will not be flagged for
> validation or linking error?

I discussed this with Bob and Volker. It turns out that there
are some special cases where it's legal in some document types to
have a link element with no cdr:ref attribute. The case that Bob
came up with is a CTGovProtocol that has a Person or Organization
for which we cannot find a match in our database. If we have a
match, we include the cdr:ref, if we don't, we don't. But we
still need an element to hold the name.

So there is a legitimate reason why we might define a linking
element without making the actual linking attribute required.

However this doesn't necessarily explain the case of OrgSiteID.

It may be desirable for someone to review our schemas, looking
for declarations of optional cdr:ref, cdr:href and cdr:xref
attributes. There are quite a few. Some of those should
probably be required. The ones that aren't might benefit from a
comment in the schema explaining why the attribute is not
required.

BZDATETIME::2010-03-09 16:18:25
BZCOMMENTOR::Alan Meyer
BZCOMMENT::6

I have made several changes in light of William's feedback on
the document.

The changes are in "General Information About Links", and in
"Link Types". I've also added a single sentence to "Pick List
Extensions" to explain that the "+=" relationship is probably
not useful but is there for completeness.

If the changes look good, we're ready for this to be converted
to XML and inserted into the CDR Help documentation.

Attachment linksummary2.doc has been added with description: Summary of CDR Server Link Capabilities - Revised

BZDATETIME::2010-03-17 13:21:07
BZCOMMENTOR::William Osei-Poku
BZCOMMENT::7

(In reply to comment #6)
> Created an attachment (id=1872) [details]
> Summary of CDR Server Link Capabilities - Revised
>
> I have made several changes in light of William's feedback on
> the document.
>
> The changes are in "General Information About Links", and in
> "Link Types". I've also added a single sentence to "Pick List
> Extensions" to explain that the "+=" relationship is probably
> not useful but is there for completeness.
>
> If the changes look good, we're ready for this to be converted
> to XML and inserted into the CDR Help documentation.

I have created the Document - CDR0000668482. I just need to QA it and format some aspects of the document.

Marked issue as Resolved.

Alan:
It looks like I can close this issue at this point, right?

BZDATETIME::2010-03-17 15:29:56
BZCOMMENTOR::Alan Meyer
BZCOMMENT::8

(In reply to comment #7)
...
> Alan:
> It looks like I can close this issue at this point, right?

That's fine with me. You might want to wait until you finish
the QA and formatting, but I'm done.

BZDATETIME::2010-03-17 17:03:56
BZCOMMENTOR::William Osei-Poku
BZCOMMENT::9

(In reply to comment #8)
> (In reply to comment #7)
> ...
> > Alan:
> > It looks like I can close this issue at this point, right?
>
> That's fine with me. You might want to wait until you finish
> the QA and formatting, but I'm done.

Yes. I just completed it. I am closing the issue now. Thank you!