List Event Updates

Returns the list of updates of an event from the Workflow module.

URL

{WSUrl}/api/events/<EventCode>/updates[[[&]show_child_events=<filter>][[&]$filter=<filter>][[&]page=<Page>][[&]page_size=<PageSize>][[&]$orderby=<field1 [desc],field2 [desc]…fieldN [desc]>]]

REQUEST METHOD

GET

URL PARAMETERS

EventCode: This parameter is provided in the URL and does not need to be sent through GET.

show_child_events: Includes updates made to the child events of the event specified.

page: Number of the page to be displayed. Valid values: 1 to the maximum number of pages. If omitted, the value 1 is used. If the value is greater than the maximum number of pages, a blank list will be returned.

page_size: Number of items displayed per page. Valid values: 1 to 1,000. If omitted, the default value of 10 is used.

filter: Query based on the OData protocol syntax for configuring filters. The fields supported are listed below. See the examples to view the operations allowed.

orderby: Orders the event updates listed on the page by field. To order by more than one field, use a comma between the field names. For descending order, add the word "desc" for each desired field. The supported fields are listed below.

FIELDS SUPPORTED BY FILTER

Guid Id;

int? Action;

DateTime Date;

string Comment;

string Property;

string OldValue;

string NewValue;

string AdditionalParameter;

Guid? AttachmentId;

string ChildEventCode;

int UpdateType;

string UpdatedBy;

The filters follow the ODATA standard (http://www.odata.org/developers/protocols/uri-conventions). The operators supported in the expression language are described in the table below:

The logical operators supported in the expression language are described in the following table:

TYPES OF DATA

String or Text: Text should be entered between single quotes (' and ').

Byte: Whole numeric value.

Double: Real number with a period (.) as a decimal separator.

Datetime: The date and time should be in 'YYYY-MM-DDT00:00:00' format, between single quotes. For example:

•    With date and time: datetime'2010-10-25T12:34:56'.

•    With date only: datetime'2010-10-25'.

KNOWN LIMITATIONS

•    The $select and $expand parameters from the ODATA standard were not implemented.

•    To use special characters such as (&) and apostrophes, see examples below:

o  To create a filter that contains "Modulo's" in the "Description" field, the apostrophe must be duplicated. For example: substringof('Modulo"s', Description).

o  To create a filter that contains "Proctor&Gamble" in the "Description" field, the "&" must be replaced by its hexadecimal coding, in this case %26. For example: substringof('Proctor'%26Gamble',Description).

•    To create a filter for a specific date – for example, for assets created on September 19^th, 2011 – the following filter will not work: (Created eq datetime'2011-09-19'). Instead, the following filter must be used: (Created ge datetime'2011-09-19')and(Created lt datetime'2011-09-20').

•    The "Comment", "OldValue", and "New Value" fields cannot be filtered.

REQUEST EXAMPLES

The first ten updates (by default, ten updates are listed at a time):

{WSUrl}/api/events/EVTC201105000052/updates

Updates 11 through 20 (second page) of any status:

{WSUrl}/api/events/EVTC201105000052/updates?page=2&page_size=10

The first ten updates including related events' updates:

{WSUrl}/api/events/EVTC201105000052/updates?show_child_events=True

Filter by "Action" field equal to 13 (property updated):

{WSUrl}/api/events/EVTC201105000052/updates?$filter=Action eq 13

Filter by string "xpto" in the "Comment" field:

{WSUrl}/api/events/EVTC201105000052/updates?$filter=substringof('xpto',Comment)

Filter by "Date" field with date between 04/24/2012 and 04/28/2012:

{WSUrl}/api/events?$filter=(Date gt datetime'2011-08-24') and (Date lt datetime'2011-08-28')

SUCCESS RESPONSE

List of objects with information on an event's updates.

Returns a WorkflowEventUpdate[].

The WorkflowEventUpdate ihas the following format:

WorkflowEventUpdate

{

Guid Id;

int? Action;

DateTime Date;

string Comment;

string Property;

string OldValue;

string NewValue;

string AdditionalParameter;

Guid? AttachmentId;

      string ChildEventCode;

int UpdateType;

string UpdatedBy;

}

The "UpdateType" field may have the following values:

0: when a property of the event is updated.

1: when a file is attached.

2: when the Progress field is updated or when there is a change in the event’s status.

The "Action" field may have the following values:

0: Event created.

1: Event closed.

2: Event reopened.

3: Event cancelled.

4: Event disassociated.

5: Progress updated.

6: Child event created.

7: Child event closed.

8: Child event reopened.

9: Child event cancelled.

10: Child event deleted.

11: Child event disassociated.

12: Progress updated for child event.

13: Event property updated.

14: People or groups added as involved.

15: People or groups removed as involved.

16: Assets associated.

17: Assets removed.

18: Files attached to event Progress tab.

19: Property updated for child event.

20: People or groups added as involved in a child event.

21: People or groups removed as involved in a child event.

22: Assets associated with child event.

23: Assets removed from child event.

24: Files attached to the Progress tab of a child event.

25: Event associated with a parent event.

26: Child event associated with parent.

27: Business components associated.

28: Business components disassociated.

29: Business components associated with a child event.

30: Business components disassociated from a child event.

31: Continuity plans associated.

32: Continuity plans disassociated.

33: Enterprise risks associated.

34: Enterprise risks disassociated.

35: Files attached to event attribute.

36: Files removed from event attribute.

37: Events associated.

38: Events disassociated.

39: Files attached to a child event attribute.

40: Files removed from a child event attribute.

41: File in event attribute updated.

42: File in child event attribute updated.

The "Property" field is completed when the value of a property in the event is updated. It contains the name of the property that was modified and, in this case, the "OldValue" and "NewValue" fields contain the former and new values for this property.

The "AdditionalParameter" field is used when certain actions require additional information. Described below is the information displayed in this field with each action specified:

Event disassociated (4): Contains the code of the event from which the event specified was disassociated.

Involved added (14 and 20): Contains the names of those included as involved in the event.

Involved removed (15 and 21): Contains the names of the people or groups involved that were removed.

Assets associated (16 and 22): Contains the names of the assets associated with the event specified.

Assets removed (17 and 23): Contains the names of the assets removed from the event specified.

File attached (18 and 24): Contains the name and attachment I of the file attached to the event specified.

SUCCESS RESPONSE EXAMPLE

[

{

"Action":13,

"AdditionalParameter":"",

"AttachmentId":null,

"ChildEventCode":null,

"Comment":"",

"Date":"\/Date(1317053182737-0300)\/",

"Id":"21b688eb-587e-4fc3-a43e-3661f707fd9f",

"NewValue":9\/26\/2011 12:00 AM,

"OldValue":null,

"Property":"StartDate",

"UpdateType":0,

"UpdatedBy":"administrator"

},

{

"Action":5,

"AdditionalParameter":"",

"AttachmentId":null,

"ChildEventCode":null,

"Comment":"Comment",

"Date":"\/Date(1317045356363-0300)\/",

"Id":"5ac2c5f3-d916-4ab8-a31a-3c1d5bf3b35b",

"NewValue":"55",

"OldValue":"0",

"Property":"Progress",

"UpdateType":2,

"UpdatedBy":"coordinator"

}

]

SUCCESS RESPONSE

HTTP status code 204: NoContent