Updating a reference to an entity

Hi,

The API documentation explains how to create a Task and add a reference to a newly created parent Task:

//Create an entity that represents a task

GenericEntity parentTask = new GenericEntity();

parentTask.Id = new EntityId();

parentTask.Id.TypeName = "Task";

parentTask.Id.Value = Guid.NewGuid().ToString();

FieldValue parentName = new FieldValue();

parentName.FieldName = "Name";

parentName.Value = "Parent Task";

parentTask.Values = new FieldValue[] { parentName };

//Create an entity that represent a child task

GenericEntity childTask = new GenericEntity();

childTask.Id = new EntityId();

childTask.Id.TypeName = "Task";

childTask.Id.Value = Guid.NewGuid().ToString();

FieldValue childName = new FieldValue();

childName.FieldName = "Name";

childName.Value = "Child Task";

childTask.Values = new FieldValue[] { childName };

//Create an entity that represents the link between the parent and the child task

GenericEntity link = new GenericEntity();

link.Id = new EntityId();

link.Id.TypeName = "WorkItemHierarchyLink";

//Create a field that references the parent task Id

FieldValue parentRef = new FieldValue();

parentRef.FieldName = "Parent";

parentRef.Value = parentTask.Id;

//Create a field that references the child task Id

FieldValue childRef = new FieldValue();

childRef.FieldName = "Child";

childRef.Value = childTask.Id;

link.Values = new FieldValue[] { parentRef, childRef };

//Now create 3 CreateMessage objects that perform the creation of the tasks

//and the link between them

CreateMessage msg1 = new CreateMessage();

msg1.Entity = parentTask;

CreateMessage msg2 = new CreateMessage();

msg2.Entity = childTask;

CreateMessage msg3 = new CreateMessage();

msg3.Entity = link;

Result[] results = client.Execute(new BaseMessage[] { msg1, msg2, msg3 });

//checks all requests succeeded

…

That's OK, but I would like to fully understand how references work when updating entities:

If I want to change the parent of a task, do I need to create a new link or just change the parent reference field? Do I have to specifically remove the existing link or it gets remove automatically?
When a reference points to a pickup table, do I also need to create a link or just change/set the referenced id in the specific field? Do I need to remove existing link (obviously if there is one)?
Same question about generic entities.
Where do I set the parent work item of a document? Just in the link?
Is it possible for just one of the messages sent to fail? May I have inconsistent/corrupted results if, for instance, the link creation fails?

Thanks in advance.

Fernando Borrego Polo January 27, 2014 18:34 Answered

Please sign in to leave a comment.

5 comments
Date Votes

Hi Fernando. First I'd like to comment you have excellent questions. I hope my answers are of good use to you and other developers.

To change the parent, you have to explicitly remove the RealWorkItemHierarchyLink and create a new one. Note that prior to the removal of the link you may have to remove dependencies as well.
References to pickup tables are direct (no link involved). You can directly set the value (as always reference values are of type EntityId. For pickups, the value is the value name, e.g. TypeName = "TrackStatus", Value = "Off Track")
Relationships between Clarizen Entities can be direct (Referece to Object field) or through a link (obviously for many <-> many relationships). Sometimes you have both a link and a reference field (e.g. Parent), but the reference field is read only, so you need to work through the link. In general:
   If there's a link entity describing the relationship, you have to use it.
   The link's main reference fields cannot be updated. You need to add a new link (and possibly delete the current one)
   If the relationship is described with a direct reference field, you can update its value with the corresponding EntityId.

I know this is a bit complicated as a generic answer. It may be easier to deal with a particular relationship, so the answer can be as simple as "use this link/reference". Please refer to the Clarizen data model wiki page, or add a post/comment in this forum.
4. Yes, the parent of a document is set on the appropriate AttachmentLink (e.g. WorkItemAttachmentLink)
5. It is possible for some of the messages to succeed and some of them to fail. If you want to process several messages as a single operation, consider using TransactionMessage, to bundle them. As the name suggests, if any of the messages in a TransactionMessage fails, the entire TransactionMessage is rolled back. BTW, TransactionMessage _inheritsfrom _BaseMessage meaning you can send several TransactionMessage_s+ other messages in a single _Execute call.

Hope this helps,

Ophir

Ophir Kenig January 28, 2014 11:35 0 votes

Thanks, it made it much clearer. One more question on the same topic. If I remove an entity, do I have to remove associated links or those are automatically deleted?

Regards.

Fernando Borrego Polo February 03, 2014 16:48 0 votes

Hi Fernando.

I've tried deleting objects (with the UI, not the API though), and the answer is "it depends". For example:

For a WorkItemAttachmentLink , the link is removed only of you delete the document (not if you delete the work item).
If you 'Delete' a user it's not actually deleted, (it still appears in a 'Deleted' state and the resource links are not removed (you can even see them in the work item Resources.
WorkItemHierarchyLinks are deleted.

In any case one can restore deleted items from the Recycle Bin, which in turn also restores the links.

Here too, we need to know exactly which link is in question, and which side of it you want to delete to come up with a concrete answer. Write a small test program, or post here for particular link types.

All in all, I'd suggest you let Clarizen decide what to do with the links. If you query a link type that is not automatically deleted, bare in mind it may point to nothing on one side.

Hope this helps.

Ophir

Ophir Kenig February 03, 2014 17:16 0 votes

I want to create a link between milestone and task.

I created a new task and link it with a project .

I also fetched all milestones under project.Now i want to link between task and milestone .

Please suggest

Bharti Kishnani July 11, 2014 07:59 0 votes

Hi Bharti.

Please open a separate post next time, your question seems not related to this one. Thanks.

In order to create a parent <-> child relationship between work items you should create a RealWorkItemHierarchyLink

with the Child & Parent fields specifying the EntityId of the appropriate work item.

If there's already such a link for the child, you need to delete it first.

Hope this helps

Ophir

Ophir Kenig July 11, 2014 10:09 0 votes

Updating a reference to an entity

5 comments Date Votes

5 comments
Date Votes