Managing events with the MACRO API

GetNewEvents - Retrieve new current event records (from the EVENTDATA table)

GetEvents - Retrieve specified current event records

GetHistoryEvents - Retrieve specified current event records from the audit trail (EVENTDATAHISTORY table)

SetEventStatus - Change the status of a current event

To use the Events API calls, you must add the following two references to your project:

· InferMed.M40.Events

· InferMed.M40.Components.Enums

Current and history events

Current event records are stored in the EVENTDATA table in the MACRO database. An audit trail of all event records (including all current records) is stored in the EVENTDATAHISTORY table.

Each event has an integer status value; the default status value for a newly created event record is 0. If the status is 0 or a negative number, the event record remains in the EVENTDATA table. If the status is changed to a positive number, the event record is removed from the EVENTDATA table (but the record and its full audit trail remains in the EVENTDATAHISTORY table).

The EventData object

When calling the API Event functions, the "event filter" object (EventData) allows you to specify the attributes of events for searching, and also contains the returned event records.

When searching, you can set zero or more of the following attributes to specify the events you wish to retrieve. If attributes are left blank, they will be ignored when retrieving records:

· Study name

· Site

· Subject Id

· Event type

· Event target (subject, visit, eForm, question)

· Event code

· Event status

· Event action

· Visit code and cycle

· eForm code and cycle

· Question code and cycle

When event records are returned by an API routine, the full details are contained in EventData objects.

Event type and target

There are defined enumerations for Event Type, Event Target and Event Action, as follows:

Enums.eEventType	Value
DataStatusChange	1
LockStatusChange	2
DCRStatusChange	3
SDVStatusChange	4
DataChange	5
NewSubject	6
UserDefined	20
None	0

Enums.eEventTargetType	Value
Subject	1
Visit	2
eForm	3
Question	4
Undefined	-1
Any	Enums.ANY_STATUS

Enums.eEventAction	Value
None	0
SendEmail	1

Return to top

GetNewEvents

Retrieve new current event records (from the EVENTDATA table).

Input

Parameter	Description
user	Currently logged-in user as returned from Login

public static List<EventData> GetNewEvents(UserProperties user, ref API.EventResult result, ref string resultError)

Output

· A list of all event records from the EVENTDATA table with status = 0 (new, unprocessed records)

· Return code indicating success or nature of failure

· resultError - further details of any errors

Return to top

GetEvents

Retrieve specified current event records.

Input

Parameter	Description
user	Currently logged-in user as returned from Login
filter	EventData object specifying attributes to match on. Leaving any attributes blank will search for all values of that attribute, e.g. if Site = "", all sites will be searched for.

public static List<EventData> GetEvents(UserProperties user, EventData filter, ref API.EventResult result, ref string resultError)

Output

· A list of all event records from the EVENTDATA table (current events) matching the specified filter

· Return code indicating success or nature of failure

· resultError - further details of any errors

Return to top

GetHistoryEvents

Retrieve specified current event records from the audit trail (EVENTDATAHISTORY table).

Note that copies of all current records from the EVENTDATA table are also held in the EVENTDATAHISTORY table.

Input

Parameter	Description
user	Currently logged-in user as returned from Login
filter	EventData object specifying attributes to match on. Leaving any attributes blank will search for all values of that attribute, e.g. if Site = "", all sites will be searched for.

public static List<EventData> GetHistoryEvents(UserProperties user, EventData filter, ref API.EventResult result, ref string resultError)

Output

· A list of all event records from the EVENTDATAHISTORY table (the event audit trail) matching the specified filter

· Return code indicating success or nature of failure

· resultError - further details of any errors

Return to top

SetEventStatus

Change the status of a current event.

This routine sets the status and message of an event in the EVENTDATA table (i.e. a current event) matching the specified filter. The EventData object must be one that has been returned from a call to GetNewEvents() or GetEvents(), because its EventDataId property is required to uniquely identify the event record.

It is not possible to change the status of an event record in the audit trail, i.e. in the EVENTDATAHISTORY table. Be aware that if an EventData object is specified that has come from the EVENTDATAHISTORY table, an attempt will be made to match the EventDataId with a record from the EVENTDATA table, and if one exists, its status will be changed.

Input

Parameter	Description
user	Currently logged-in user as returned from Login
evt	EventData object specifying a current event (as returned from GetNewEvents() or GetEvents())
status	Integer status value If the new status value is 0 or a negative integer, the event record is updated and remains in the EVENTDATA table. If the new status is a positive integer, the event record is considered to have been processed and is removed from the EVENTDATA table. In either case, whenever the event status is changed, a row will be added to the EVENTDATAHISTORY table (the audit trail).
evMsg	Optional message associated with this event status change. Use an empty string if no message is required.

public static API.EventResult SetEventStatus(UserProperties user, EventData evt, int status, string evMsg, ref string resultError)

Output

· Return code indicating success or nature of failure

· resultError - further details of any errors

Return to top

Event management return codes

The Event management routines return an integer code as type API.EventResult indicating the result, as listed in the table below:

Code	Value	Description
0	Success	The operation was successful
1	DbError	A database error occurred
2	OtherError	An unexpected error occurred
3	EventNotExists	The specified event does not exist (when changing event status)
4	SqlError	An SQL error occurred
5	NoUpdateRequired	SetEventStatus was called with the existing status

Return to top