{scrollbar:icons=false}
h1. {page-info:title}
{section}
{column:width=75%}
{panel:title=Contents of this Page}
{toc:minLevel=2}
{panel}
{column}
{column}
{align:right}{include:Menu LexEVS 6.0 CTS2 to Include}{align}
{column}
{section}

h2. Introduction
LexEVS CTS2 Code System Authoring API provides capability to author Code System and its contents.

Here are the authoring functions that can be performed on Associations in a Code System:

h3. Create
This function provides capability to create:
* New Association
* Add Qualifiers to the Association
* Determine Source and Target Code Systems for the Association
* New Coding Scheme consisting of mappings of one system's concepts to another.
* New Mapping for an existing mapping scheme
* New Association for an existing coding scheme.

h3. Status Change
This function provides capability to update Status attributes:
* Association Status

h2. Interface

{code}org.lexevs.cts2.LexEvsCTS2 cts2 = org.lexevs.cts2.LexEvsCTS2Impl.defaultInstance();
org.lexevs.cts2.author.AssociationAuthoringOperation associationAuthoring = 
cts2.getAuthoringOperation().getAssociationAuthoringOperation();{code}


h2. Revision Information
Authoring requires information helping to determine whether the edited coding scheme element is new or revises an existing association. This requires not only a containing revision, but also a entry state object for each versionable element of the Association being created.  A single object of each is passed into the association creating method providing mandatory information about this revision which in most use cases here is a new association.  

h3. org.LexGrid.versions.Revision 
Revision object has following attributes:

* *java.lang.String changeAgent* - (Optional) The source that participated in this particular change.
* *java.lang.String changeInstruction* - (Optional) A human or machine readable set of instructions on how to apply this change.
* *java.lang.String revisionId* - (*Mandatory*) The unique identifier of this revision.
* *java.lang.Long editOrder* - (Optional) The relative order that this revision is to be applied if in a systemRelease.
* *java.util.Date revisionDate* - (Optional) The end date for which this version is operative (considered commited).
* *java.lang.String description* -  (Optional) The description of the resource/change.
* *java.lang.String systemReleaseURI* - (Optional) The official URI of this release

h3. org.LexGrid.versions.EntryState

* *java.lang.String containingRevision* - (*Mandatory*)The revision that contains this particular entry state change
 *private java.lang.Long relativeOrder* - (Optional)The relative order that this state change should be applied within the context of the containing revision
* *private org.LexGrid.versions.types.ChangeType changeType* - (Context determined.  NEW for new association)The type of change that occurred between this state and the previous.
* *private java.lang.String prevRevision* -  (Optional)The unique identifier of the state of this entry was at prior to this change.

h2. Association Authoring Functions

h3. Create Association Operations

{{createAssociation(boolean createMappingScheme, Revision revision, EntryState entryState, AbsoluteCodingSchemeVersionReference mappingScheme, AbsoluteCodingSchemeVersionReference sourceCodeSystemIdentifier, AbsoluteCodingSchemeVersionReference targetCodeSystemIdentifier, String sourceConceptCodeIdentifier, String targetConceptCodeIdentifier, String relationsContainerName, String associationType, AssociationQualification[] associationQualifiers)}}

|| *Description:* | Creates new Association |
|| *Input:* | * *boolean createMappingScheme* - create a mapping coding scheme if one does not exist
* *org.LexGrid.versions.Revision revision* - create a mapping coding scheme if one does not exist
* *org.LexGrid.versions.EntryState entryState* - revision data container granular to the versionable class.
* *Aorg.LexGrid.LexBIG.DataModel.Core.AbsoluteCodingSchemeVersionReference mappingScheme* - existing mapping scheme, required if adding mapped association
* *org.LexGrid.LexBIG.DataModel.Core.AbsoluteCodingSchemeVersionReference sourceCodeSystemIdentifier* - minimum code system identification
* *org.LexGrid.LexBIG.DataModel.Core.AbsoluteCodingSchemeVersionReference targetCodeSystemIdentifier* - minimum code system identification
* *java.lang.String sourceConceptCodeIdentifier* - source concept code	
* *java.lang.String targetConceptCodeIdentifier* - target concept code
* *java.lang.String relationsContainerName* - relations container identifier
* *java.lang.String associationType* - association type identifier
* *org.LexGrid.relations.AssociationQualification[] associationQualifiers* - qualifications to add to this association |
|| *Output:* | *_org.LexGrid.relations.AssociationSource_* - Created Association Structure |
|| *Exception:* | *_org.LexGrid.LexBIG.Exceptions.LBException_* |
|| *Sample Call:* | * _Step 1:_ Create Revision Elements:
{code}Revision revision = new Revision(); - initalize Revision object
revision.setChangeAgent("Mayo Foundation"); - Set the change agent if desired
Text changeInstructions = new Text(); - initialize Text Object
changeInstructions.setContent("To be applied at next source release"); - Define change instructions if desired.
revision.setChangeInstructions(changeInstructions); - Set change instructions
revision.setEditOrder(new Long(1)); - Set edit order
EntityDescription entityDescription = new EntityDescription(); - Initialize EntityDescription Object
entityDescription.setContent("TestCTS2AssociationRevision"); - Set content for this object
revision.setEntityDescription(entityDescription); - Set revision entityDescription

EntryState entryState = new EntryState(); - Initialize EntryStateObject
entryState.setChangeType(ChangeType.NEW); - This is a new association -- set ChangeType to "NEW"
entryState.setContainingRevision("FirstRevision_12_09_2010"); - Define the revision identifier 
entryState.setRelativeOrder(new Long(1)); - Set relative order{code}
* _Step 2:_ Define a source scheme:
{code}AbsoluteCodingSchemeVersionReference sourceCodeSystemIdentifier = new AbsoluteCodingSchemeVersionReference();
sourceCodeSystemIdentifier.setCodingSchemeURN("http://ncicb.nci.nih.gov/xml/owl/EVS/Thesaurus.owl#");
sourceCodeSystemIdentifier.setCodingSchemeVersion(10.10a);{code}
* _Step 3:_ Define a target scheme:
{code}AbsoluteCodingSchemeVersionReference targetCodeSystemIdentifier = new AbsoluteCodingSchemeVersionReference();
targetCodeSystemIdentifier.setCodingSchemeURN("urn:oid:2.16.840.1.113883.6.2");
targetCodeSystemIdentifier.setCodingSchemeVersion(200909);{code}
* _Step 4:_ Name the unique identifier of the source concept:
{code}String sourceConceptCodeIdentifier = "C27469";{code}
* _Step 5:_ Name the unique identifier of the target concept:
{code}String targetConceptCodeIdentifier = "199";{code}
* _Step 6:_ Identify or name a new relations container
{code}String relationsContainerName = "relations";{code}
* _Step 7:_ Name the association
{code}String associationType = "SY";{code}
* _Step 8:_ call create method to create the association:
_AssociationSource association = associationAuthoringOp.createAssociation(false, revision, entryState,_\\
\\
_null, sourceCodeSystemIdentifier, targetCodeSystemIdentifier,_
_sourceConceptCodeIdentifier, targetConceptCodeIdentifier,_
_relationsContainerName, associationType, null);_ |

h3. Update Association Operations
{{updateAssociationStatus(Revision revision, EntryState entryState, AbsoluteCodingSchemeVersionReference scheme, String relationsContainer, String associationName, String sourceCode, String sourceNamespace, String targetCode, String targetNamespace, String instanceId, String status, boolean isActive)}}

|| *Description:* | Updates Association Status |
|| *Input:* | * *org.LexGrid.versions.Revision revision* - create a mapping coding scheme if one does not exist
* *org.LexGrid.versions.EntryState entryState* - revision data container granular to the versionable class.
* *org.LexGrid.LexBIG.DataModel.Core.AbsoluteCodingSchemeVersionReference scheme* - Scheme targeted for update.
* *java.lang.String relationsContainerName* - relations container identifier
* *java.lang.String associationName* - association identifier
* *java.lang.String sourcCode* - source concept code	
* *java.lang.String sourceNamespace* - code system identification 
* *java.lang.String targetCode* - target concept code
* *java.lang.String targetNamespace* - minimum code system identification
* *java.lang.String instanceId*  - instance identifier for the association
* *java.lang.String status* - Status designation can be user defined
* *boolean isActive* - flag for Active status |
|| *Output:* | *_boolean_* - flag for successful update |
|| *Exception:* | *_org.LexGrid.LexBIG.Exceptions.LBException_* |
|| *Sample Call:* | * _Step 1:_ Create Revision Elements:
{code}Revision revision = new Revision(); - initalize Revision object
revision.setChangeAgent("Mayo Foundation"); - Set the change agent if desired
Text changeInstructions = new Text(); - initialize Text Object
changeInstructions.setContent("To be applied at next source release"); - Define change instructions if desired.
revision.setChangeInstructions(changeInstructions); - Set change instructions
revision.setEditOrder(new Long(1)); - Set edit order
EntityDescription entityDescription = new EntityDescription(); - Initialize EntityDescription Object
entityDescription.setContent("TestCTS2AssociationRevision"); - Set content for this object
revision.setEntityDescription(entityDescription); - Set revision entityDescription

EntryState entryState = new EntryState(); - Initialize EntryStateObject
entryState.setChangeType(ChangeType.MODIFY); - Association is being revised.  Set ChangeType to "MODIFY"
entryState.setContainingRevision("FirstRevision_12_09_2010"); - Define the revision identifier 
entryState.setRelativeOrder(new Long(1)); - Set relative order{code}
* _Step 2:_ Define the scheme for the association update:
{code}AbsoluteCodingSchemeVersionReference scheme = new AbsoluteCodingSchemeVersionReference();
scheme.setCodingSchemeURN("http://ncicb.nci.nih.gov/xml/owl/EVS/Thesaurus.owl#");
scheme.setCodingSchemeVersion(10.10a);{code}
* _Step 3:_ Name the unique identifier of the source concept:
{code}String sourceCode = "C27469";{code}
* _Step 4:_ Define the namespace of the source concept supported for this coding scheme
{code}String sourceNamespace = "NCI Thesaurus"{code}
* _Step 5:_ Name the unique identifier of the target concept:
{code}String targetCode = "C27469";{code}
* _Step 6:_ Identify or name a new relations container
{code}String relationsContainerName = "relations";{code}
* _Step 7:_ Define the association
{code}String associationName = "Disease_Has_Abnormal_Cell";{code}
* _Step 8:_ Identify the instance of this association to be updated.
{code}String instanceID = "instance001";{code}
* _Step 9:_ Define the new status
{code}String status = "PENDING_RETIREMENT";{code}
* _Step 10:_ Set isActive flag if necessary
{code}boolean isActive = false;{code}
* _Step 11:_ call create method to create the association:
 _AssociationSource association = associationAuthoringOp.updateAssociationStatus(revision, entryState,_\\
\\
_scheme, relationsContainerName, associationName, sourceCode,_
_namespace, targetCode, namespace, instanceId, status,_
_isActive);_ |

{scrollbar:icons=false}