Colectica Repository can store any metadata items that conform to the ISO 11179 naming scheme for registered items. The DDI 3 Addin for Colectica Repository additionally allows for indexing of contextual and relationship information. Here is a brief code example showing how DDI 3 items can be registered in the Colectica Repository.
First we will create some DDI 3 based metadata using the Colectica SDK. If you don’t have the SDK you can create the DDI 3 by hand or using your favorite XML library.
// Create a DDI 3 Concept using the Colectica SDK Concept concept = new Concept() { AgencyId = "example.org" }; concept.ItemName["en-US"] = "Given Name"; concept.Description["en-US"] = @"A character-string (e.g. `Billy' and `Peter') given to people as a first name (or, in most Western countries, as a middle name), usually shortly after birth."; // Create a DDI 3 Question using the Colectica SDK Question q1 = new Question() { AgencyId = "example.org" }; q1.QuestionText["en-US"] = "What is your first name?"; TextDomain domain = new TextDomain(); domain.Label["en-US"] = "First Name"; q1.ResponseDomains.Add(domain); // Link the question and concept q1.Concepts.Add(concept);
Then we will create the repository client, using the supplied credentials.
// Create the web services client var client = new WcfRepositoryClient( "username", "password", "localhost", 19893);
We can Register any object made by the Colectica SDK using the built in mappings.
// Register a 11179 administered item using // the Repository Client helper functions client.RegisterItem(concept, new CommitOptions());
Alternatively, we can access the web services layer and construct the proper SOAP payload.
// Register a 11179 administered item using the Web Services directly Collection<Note> notes = new Collection<Note>(); string serialization = q1.GetXmlRepresentation(notes).OuterXml; RepositoryItem ri = new RepositoryItem() { CompositeId = q1.CompositeId, // agency, id, and version Item = serialization, // item's serialization ItemType = q1.ItemType, // model defined item type identifier IsDepricated = false, IsPublished = q1.IsPublished, IsProvisional = false, // only used in the local repository Notes = notes, // notes about the item being registered VersionDate = q1.VersionDate, VersionRationale = q1.VersionRationale, VersionResponsibility = q1.VersionResponsibility }; client.RegisterItem(ri, new CommitOptions());
As you can see, we added both the DDI concept and the DDI question item to the repository. The Colectica SDK has methods to gather all items that are linked and create sets of items to be registered. It also has the ability to detect changed items automatically, so a program can quickly determine which items should have new versions registered after a user action.
Update 1: Registering items in a DDI instance
Here is more information about registering items in the Repository based on some followup questions.
When adding a concept to a question, the hierarchical relationship is established. Is this inline, or by reference at the XML level?.
The DDI 3 standard allows for either including items inline or by references in many locations. Colectica Repository will process and store items using either format. If it is a DDI 3 item, the Repository will additionally index the text and relationship information about the item using the DDI 3 Addin. Note that only the item being registered and its relationship are processed, each item must still be registered individually or in a batch operation.
Colectica Designer will always use the referencing mechanisms in DDI when interacting with the Repository. This is for speed of processing and to allow the easiest sharing and harmonization of items across multiple Studies and Instances. You can learn more about how Designer determines item boundaries by reading about Concise Bounded Descriptions.
How can I register all items in a DDI Instance? How can I update only the changed items in a DDI instance?
If you are using DDI with an XML library, you can use the following xpath queries to find all the items in your Instance to register.
//*[@isVersionable] //*[@isMaintainable]
You can then loop over the XML nodes returned by the XPath and register the results. If you are using the Colectica SDK, you can find all items in an Instance as follows:
// obtain your DDI Instance in some fashion DdiInstance instance = YourDdiInstance(); // Find all items ItemGatherer gatherer = new ItemGatherer(); instance.Accept(gatherer); Collection<IVersionable> allItems = gatherer.Items; // You can also find only the modified items DirtyItemGatherer gatherer = new DirtyItemGatherer(); instance.Accept(gatherer); Collection<IVersionable> changedItems = gatherer.DirtyItems;
How do I export a whole instance to DDI3?
There are several ways to export a DDI instance from the Repository. One way is to use the Repositoy’s command line tools and to write an XML document. Another is to programmatically export a DDI instance using the SDK:
// obtain your DDI Instance in some fashion. // Only the identification is needed since we will populate the instance DdiInstance instance = YourDdiInstance(); // populate the entire class hierarchy from the Repository GraphPopulator populator = new GraphPopulator(client); instance.Accept(populator); // Create the XML document for the DDI Instance DDIWorkflowSerializer serializer = new DDIWorkflowSerializer(); XmlDocument doc = serializer.Serialize(instance);
A third option is to use an XML library and construct the DDI Instance.
Hi Dan,
I’m trying to use the SDK to programatically work with our Colectica repository. Trouble is, I can’t figure out how to connect to the repository, i.e. how to write the YourDdiInstance() method above.
Hope I’m not just being thick 🙂
Thanks,
Bill
Hi Bill,
I’ve written another post to explain retrieving items, and DDI items specifically, from the Colectica Repository. You can find it here.
Cheers! Dan