List Events

Returns a paginated list of the events from the Workflow module.

URL

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

REQUEST METHOD

GET

URL PARAMETERS

status: Status filter for Workflow events. This list of statuses is comma delimited. A status may have one of the following possible numeric values: 0 or Cancelled, 1 or Open, or 2 or Closed. If omitted, all events are returned.

page: Number of the page to be displayed. Valid values: from 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: from 1 to 1,000. If omitted, the default value of 10 items 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 events 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 field. The supported fields are listed below.

FIELDS SUPPORTED BY FILTER

string Title;

string Code;

string Description;

byte Urgency;

byte Severity;

byte Relevance;

byte USR;

byte Status;

DateTime? UpdatedOn;

DateTime? StartDate;

DateTime? EndDate;

DateTime? ExpectedStartDate;

DateTime? ExpectedEndDate;

DateTime? Deadline;

string Author;

string Responsible;

string Coordinator;

string FirstReviewer;

string SecondReviewer;

string ThirdReviewer;

string Origin;

string ParentEvent;

byte Progress;

DateTime Created;

double? Value;

bool Notify;

string LastUpdatedBy;

string ProjectLeader;

double? Latitude;

double? Longitude;

string EventType;

object CustomAttributes;

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 following table:

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, as in the following 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').

•    Filters for attributes apply only to Text and List of Options (Single Selection and Multiple Selection) attributes.

REQUEST EXAMPLES

The first ten events of any status (by default, 10 events are listed at a time):

{WSUrl}/api/events

The first ten closed events:

{WSUrl}/api/events?status=2

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

{WSUrl}/api/events?page=2

The first five events of any status:

{WSUrl}/api/events?page_size=5

Events 15 through 21 (third page, size 7) that are closed:

{WSUrl}/api/events?status=2=&page=3&page_size=7

Filter by "Urgency" field with a value equal to 3:

{WSUrl}/api/events?$filter=Urgency eq 3

Filter by a portion of a string in the "Title" field:

{WSUrl}/api/events?$filter=substringof('support',Title)

Filter by a complete string in the "Title" field:

{WSUrl}/api/events?$filter=Title eq 'support ticket from marketing'

Filter by the "Value" field with a value less than 20:

{WSUrl}/api/events?$filter=Value lt 20

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

{WSUrl}/api/events?$filter=(Deadline ge datetime'2012-04-24') and (Deadline le datetime'2012-04-28')

Filter mainly by event progress and secondly by date created (in descending order):

{WSUrl}/api/events?$orderby=Progress, Created desc

Filter by open events with “Urgency” field of value equal to 5, ordered by the date they were updated:

{WSUrl}/api/events?status=Open&$filter=Urgency eq 5&$orderby=UpdatedOn desc

Filter by events closed on 02/19/2012:

{WSUrl}/api/events?status=2&$filter=(EndDate ge datetime'2012-02-19')and(EndDate lt datetime'2012-02-20')

Filter by events with author "John":

{WSUrl}/api/events?$filter=substringof('John',Author)

Filter by Risk events, ordered by the date they were updated (in increasing order):

{WSUrl}/api/events?$filter=substringof('Risk',EventType)&$orderby=UpdatedOn desc

Filter by Text attribute. Keep in mind that event attribute filters require the CustomAttributes field in the request:

{WSUrl}/api/events?$filter=substringof('Marketing',CustomAttributes/textattribute)

Filter by E-mail attribute to display events with e-mails different from the specified domain. Supports the same features as filters for Text attributes:

{WSUrl}/api/events?$filter=CustomAttributes/emailattribute@corporate.com'

Filter by Link attribute to display events with a specific web address. Supports the same features as filters for Text attributes:

{WSUrl}/api/events?$filter=CustomAttributes/linkattribute eq 'http://example.com'

Filter by Number attribute to display events with a specific number, such as 40 in the example:

{WSUrl}/api/events?$filter=CustomAttributes/numberattrib eq 40

Filter by Single Selection List of Options attribute. Supports the same features as filters for Text attributes:

{WSUrl}/api/events?$filter=CustomAttributes/atribsingleselect eq 'option1'

To illustrate these attribute filters, consider a Multiple Selection List of Options attribute named "atribmultiselect" which can have one of the following values: "op1", "op2", and "op3". Also consider the following events and their respective values:

Event 1: op1

Event 2: op2

Event 3: op3

Event 4: op1, op2

Event 5: op1, op3

Event 6: op2, op3

Event 7: op1, op2, op3

Event 8: "empty"

Filter for events with "op1".

{WSUrl}/api/events?$filter=CustomAttributes/atribmultiselect/any(i: i eq 'op1')

Returns Event 1, Event 4, Event 5, and Event 7.

Filter for events with only "op1".

{WSUrl}/api/events?$filter=CustomAttributes/atribmultiselect/any() and CustomAttributes/atribmultiselect/all(i: i eq 'op1')

Returns Event 1.

Filter for events with either "op1" or no option.

{WSUrl}/api/events?$filter=CustomAttributes/atribmultiselect/all(i: i eq 'op1')

Returns Event 1 and Event 8.

Filter for events with both "op1" and "op2".

{WSUrl}/api/events?$filter=CustomAttributes/atribmultiselect/any(i: i eq 'op1') and CustomAttributes/atribmultiselect/any(i: i eq 'op2')

Returns Event 4 and Event 7.

Filter for events with "op1" or "op2".

{WSUrl}/api/events?$filter=CustomAttributes/atribmultiselect/any(i: i eq 'op1' or i eq 'op2')

Returns Event 1, Event 2, Event 4, Event 5, Event 6, and Event 7.

Filter for events with only "op1" and "op2".

{WSUrl}/api/events?$filter=CustomAttributes/atribmultiselect/any(i: i eq 'op1') and CustomAttributes/atribmultiselect/any(i: i eq 'op2') and CustomAttributes/atribmultiselect/all(i: i eq 'op1' or i eq 'op2')

Returns Event 4.

SUCCESS RESPONSE

List of objects with information on the events according to the filters and page size specified.

Returns a WorkflowEvent[].

The WorkflowEvent object is in the following format:

WorkflowEvent

{

Guid Id;

string Title;

string Code;

string Description;

byte Urgency;

byte Severity;

byte Relevance;

byte USR;

EventState Status;

DateTime? UpdatedOn;

DateTime? StartDate;

DateTime? EndDate;

DateTime? ExpectedStartDate;

DateTime? ExpectedEndDate;

DateTime? Deadline;

string Author;

string Responsible;

string Coordinator;

string FirstReviewer;

string SecondReviewer;

string ThirdReviewer;

string Origin;

string ParentEvent;

byte Progress;

DateTime Created;

double? Value;

string LastUpdatedBy;

string ProjectLeader;

double? Latitude;

double? Longitude;

string GeolocationDescription;

string EventType;

string InvolvedsNames;

string AssetsNames;

object CustomAttributes;

}

SUCCESS RESPONSE EXAMPLE

{

"Id" :"aab251eb-791d-43cc-adac-0460c5d8c53f",

"Title" :"Event title",

"Code" :"EVTD201109000720",

"Description" :"Event description",

"Urgency" :5,

"Severity" :4,

"Relevance" :3,

"USR" :60,

"Status" :1,

"Created" :"\/Date(1316527841617-0300)\/",

"Deadline" :"\/Date(1316574000000-0300)\/",

"ExpectedStartDate" :"\/Date(1316574000000-0300)\/",

"StartDate" :"\/Date(1316574000000-0300)\/",

"ExpectedEndDate" :"\/Date(1316574000000-0300)\/",

"EndDate" :"\/Date(1316638025603-0300)\/",

"UpdatedOn" :"\/Date(1316638025603-0300)\/",

"Author" :"Administrator",

"AuthorId" :"84428d3f-cd41-11e2-9459-22ddd55f8100",

"Coordinator" :"Administrator",

"CoordinatorData" :{"Id":"5938d97a-bd43-11e0-94f0-001ec91f4b0a",

"Name" :"John Smith","Type":"Person"},

"Responsible" :"HR Dept",

"ResponsibleData" :{"Id":"c1e5cf48-b3d5-11e0-8b69-001ec91f4b0a","Name":"HR Dept","Type":"Group"},

"InvolvedsNames" :"John Smith;HR Dept;Administrator",

"Progress" :66,

"Value" :1,

"LastUpdatedBy" :"Administrator",

"ProjectLeader" :"Administrator",

"Notify" :false,

"Latitude" :40.477552,

"Longitude" :-3.696289,

"GeolocationDescription" :"Location description ",

"Origin" :"PRJR11007",

"ParentEvent" :"EVTR201203023756",

"EventType" :"Risk Event",

"AssetsNames" :"Windows Server;Linux Server;Environment;Datacenter "

"CustomAttributes" : {

"number_customized" : 7,

"text_customized" : "text",

"date_customized" : "\/Date(324615600000-0300)\/"

"formula":{"Status":"Ok","Value":27.0}

}

}