08 Getting Event Info Using an API
Here's how to get event info using an API.
Getting Event Info Using an API
You can request event information from CMO using your API. CMO will send data tied to the specific EventID of your request. Details on the request and response formats are detailed below. Example API requests and responses are also provided as a template here.
GET events/{eventID}
Returns a single Event, specified by Event ID.
Usage Notes:
- A HTTP 401 will return if user is not authenticated.
- A HTTP 403 will return if user does not have permission to view the event (to view event user must have role permission 'Allow Edit' or 'Allow Read only perform').
- A HTTP 400 with message 'Event with ID = {eventID} was not found' in case when event was not found.
Resource Information
| Response formats | JSON |
| Response model | event model. |
| Requires authentication? | Yes |
| Rate limited? | No (may be limited on server where app is hosted) |
Parameters
| Name | Type | Default |
| eventID | UUID (GUID in .NET) | ------- |
Response Model (Result)
| Property Name | Property Type | Can be null | Example |
|---|---|---|---|
| EventID | UUID (.NET GUID) | no | 111afb44-efd2-42e5-aea5-a0e7aa98ae95 |
| CompanyID | number (.NET long) | no | 2 |
| OrgUnitID | number (.NET long) | yes | 2 |
| EntityID | UUID (.NET GUID) | no | 111afb44-efd2-42e5-aea5-a0e7aa98ae95 |
| EntityTypeID | number (.NET long) | yes | 2 |
| TemplateID | number (.NET long) | no | 2 |
| EventStartDate | DateTime (.NET DateTime) | yes | 2019-03-01T01:35:07.6422376Z |
| EventDate | DateTime (.NET DateTime) | yes | 2019-03-01T01:35:07.6422376Z |
| DueDate | DateTime (.NET DateTime) | yes | 2019-03-01T01:35:07.6422376Z |
| EndDate | DateTime (.NET DateTime) | yes | 2019-03-01T01:35:07.6422376Z |
| ReporterUserID | number (.NET long) | yes | 2 |
| EventTitle | string (.NET string) | yes | event title |
| GpsCoordinates | (see GPS type structure bellow) | yes | *see type structure bellow |
| FirstReminder | number (.NET int) | yes | 2 |
| SecondReminder | number (.NET int) | yes | 2 |
| SyncStatus | number (.NET int) | yes | 2 |
| BaseScore | double-precision floating-point number (.NET double) |
yes | 2.15 |
| TargetScore | double-precision floating-point number (.NET double) |
yes | 2.15 |
| StatusID | number (.NET long) | yes | 2 |
| SubStatusID | number (.NET int) | yes | 2 |
| CategoryTypeSeverities | list of CategoryTypeSeverity (see CategoryTypeSeverity type structure bellow) | yes | *see type structure bellow |
| ExecutiveSummary | string (.NET string) | yes | text |
| Recommendations | string (.NET string) | yes | text |
| PartiesInvolved | list of PartyInvolved (see PartyInvolved type structure bellow) | yes | *see type structure bellow |
| ClassificationIDs | list of UUIDs (list of .NET GUIDs) | yes | [111afb44-efd2-42e5-aea5-a0e7aa98ae95] |
| Confidential | boolean | no | false |
| ConfidentialUserIDs | list of numbers (list of .NET numbers) | yes | [1, 2] |
| CustomFields | list of CustomField (see CustomField type structure bellow) | yes | *see type structure bellow |
Gps Type Structure:
| Property Name | Property Type | Can be null | Example |
|---|---|---|---|
| X | double-precision floating-point number (.NET double) |
no | 2.01 |
| Y | double-precision floating-point number (.NET double) |
no | 2.01 |
| Z | double-precision floating-point number (.NET double) |
no | 2.01 |
CategoryTypeSeverity Type Structure:
| Property Name | Property Type | Can be null | Example |
|---|---|---|---|
| CategoryID | number (.NET long) | yes | 2 |
| TypeID | number (.NET long) | yes | 2 |
| SeverityID | UUID (.NET GUID) | yes | 111afb44-efd2-42e5-aea5-a0e7aa98ae95 |
PartyInvolved Type Structure:
| Property Name | Property Type | Can be null | Example |
|---|---|---|---|
| UserID | number (.NET long) | no | 2 |
| InvolvementTypeID | number (.NET long) | yes | 2 |
CustomField Type Structure:
| Property Name | Property Type | Can be null | Example |
|---|---|---|---|
| CustomFieldID | number (.NET long) | no | 2 |
| Value | string (.NET string) | yes | string value or json strin for complex custom field type see table bellow |
Custom Field Value Format
| Custom field type | Value type |
|---|---|
| TextBox | string (.NET string) |
| Calendar | DateTime (.NET DateTime) |
| MultilineTextBox | string (.NET string) |
| DropDown | string (.NET string) |
| AjaxDropDown | string (.NET string) |
| UserList | number (.NET long) |
| MultipleSelect | list of string (.NET string) |
| RadioButton | string (.NET string) |
| CheckBox | list of string (.NET string) |
| RiskAssessment | RiskAssessment type |
| GPS | Gps type |
| DocumentFile | UUID (.NET GUID) |
| XML | UUID (.NET GUID) |
RiskAssessment Type Structure:
| Property name | Property Type | Required? |
|---|---|---|
| ConsequenceCode | number (.NET integer) | Yes |
| LikelihoodCode | number (.NET integer) | Yes |
Gps (Custom Field) Type Structure:
| Property name | Property Type | Required? |
|---|---|---|
| Latitude | double-precision floating-point number (.NET double) |
Yes |
| Longitude | double-precision floating-point number (.NET double) |
Yes |
Example Request:
curl -X GET "https://cmo/api/events/?eventID=b4ad6458-e4de-4e64-97e1-a0547604ee0d" -H "cache-control: no-cache" -H "company: 2"
Example Response:
{
"eventID": "b4ad6458-e4de-4e64-97e1-a0547604ee0d",
"companyID": 2,
"orgUnitID": 4,
"entityID": "d06f038f-85a7-4f72-b55f-da0f89fcff25",
"templateID": 52,
"eventStartDate": "2019-02-11T16:59:59.997",
"eventDate": "2019-02-11T16:59:59.997",
"dueDate": "2019-02-14T16:59:59.997",
"reporterUserID": 2,
"eventTitle": "CWS form 11Feb2019",
"gpsCoordinates": {
"x": -30.442976,
"y": 136.849222
},
"firstReminder": 1,
"secondReminder": 5,
"syncStatus": 1,
"statusID": 26,
"customFields": [
{
"customFieldID": 6,
"value": "white"
},
{
"customFieldID": 4,
"value": ""
}
]
}
Authentication
- User send POST request with login and password to token controller (controller location is: https://cmo_server_url/api/token).
- If system is able to authenticate a user based on provided login and password then the system will return special token.
- To send request to event api an user need to include the token (mentioned in previous point) into the request, ie add 'Authorization' header with token, for instance (for cURL) it looks like: -H 'Authorization: Bearer token_is_here'. The system will check that token is valid on every request. If token is valid, then system will assume that request is performed by an user which login and password were provided in the first point.
- Note there are two ways to call event api for dependent company (not main company in the same cmo instance):
- Authenticate as fake user which system silently creates for every company
- Specify company identifier in the request header, for instane for cURL it looks like: -H 'company: 42', where 42 is an identifier of a dependent company.