Skip to main content
Mitratech Success Center

07_Creating Events Using an API

Here's how to create your events using an API.

Logging Events with an API

CMO now provides users the option to log events through an External API. These events can then be assigned to specific users and personnel to fill out based upon the parameters you set with the API. The process and fields included are detailed below, along with multiple examples that you can draw from as a template

Once the information is sent from your API to CMO, the event can be found in the "Event List" tab of the application. Search by the "Event Tile" field that you added in the API, or any other searchable field available to you. The response the API receives on a successful sync should match the URL of the event in the system. 

POST events/

Creates an event based on json model from an API.

Usage Notes:

  • A HTTP 401 will return if user is not authenticated.
  • A HTTP 403 will return if user does not have at least one role where option Event Permissions -> 'Allow create via API' is enabled.
  • A HTTP 400 with message 'Payload is empty' will return if payload is null.
  • A HTTP 400 will return if response model violate validation rules. A request will contain validation error messages.

Resource URl

url_to_cmo_application_instance/api/events/

where url_to_cmo_application_instance is url to cmo web site.

Resource Information

Response formats JSON
Response model identifier of created event.
Requires authentication? Yes
Rate limited? No (may be limited on server where app is hosted)

Request Model (Payload)

Property Name Property Type Required? Default value Example Notes
CompanyID
 
CompanyName
number (.NET long)
 
string (.NET string)
Yes (one of two is required: 
id or name)
  17
 
cmo company
 
OrgUnitID
 
OrgUnitName
number (.NET long)
 
string (.NET string)
Required if BR -> 
Hide All Org Units is 
on (one of two is required: 
id or name)
null if not required 21
 
cmo org unit
 
EntityID
 
EntityName
UUID (.NET GUID)
 
string (.NET string)
Yes (one of two is required: 
id or name)
  63bd1683-f25b-4dba-a583-e32977c292f8
 
cmo entity name
 
EntityTypeID
 
EntityTypeName
number (.NET long)
 
string (.NET string)
Required if BR -> 
Entity Type Mandatory is 
on (one of two is required: 
id or name)
null if not required  42
 
cmo entity type name
 
TemplateID
 
TemplateName
number (.NET long)
 
string (.NET string)
Yes (one of two is required: 
id or name)
  21
 
cmo template name
 
EventStartDate DateTime 
(.Net DateTime)
Yes if template Form Dates:
Event Start Date is on
null if disabled 2019-03-01T06:02:03.1676434Z Should be at the end of the 
day in company time zone 
if Form ->Allow Scheduling by 
the hour / minute is off
EventDate DateTime 
(.Net DateTime)
Yes if template
Form Dates: Event Date is on
null if disabled 2019-03-01T06:02:03.1676434Z Should be at the end of the 
day in company time zone 
if Form ->Allow Scheduling by 
the hour / minute is off
DueDate DateTime 
(.Net DateTime)
Yes if template
Form Dates: Due Date is on
null if disabled 2019-03-01T06:02:03.1676434Z Should be at the end of the 
day in company time zone 
if Form ->Allow Scheduling by 
the hour / minute is off
EndDate DateTime 
(.Net DateTime)
Yes if template
Form Dates: End Date is on
null if disabled 2019-03-01T06:02:03.1676434Z Should be at the end of the 
day in company time zone 
if Form ->Allow Scheduling by 
the hour / minute is off
ReporterUserID
 
ReporterLogin
 
ReporterName
number (.NET long)
 
string (.NET string)
 
string (.NET string)
Yes (one of three is required)   42
 
john.doe
 
John Doe
 
 EventTitle string (.NET string) Yes if BR-> Title is on If BR-> Auto
create Event title
is on, then will be
generated:
a) based
on Org Unit if template 
Event Title to be based 
on Org Unit and Sequence
is on
b) based on template
name, otherwise
 event name Should be unique if 
tempalte: Event Title must 
be unique is on
GpsCoordinates type: GpsCoordinates  No  null   To set coordinates user
must have a role where
Allow view and change 
Event GPS coordinates is on
FirstReminder number (.NET int) No 1 123 To set value user
must have a role where 
Allow Reminder Intervals is on
 
Value must be between 0 ... 999
(inclusive)
SecondReminder number (.NET int) No 5 321 To set value user
must have a role where 
Allow Reminder Intervals is on
 
Value must be between 0 ... 999 
(inclusive)
SyncStatus number (.NET int) No template New Events 
default sync status 
(1 or 3)
1 Allowed values: 
1 (always available),
3 (only if template 
Available On Mobile is on)
BaseScore number (.NET int) No   54 to set value BR->
Base Score, Target Score
should be on
Should be between 0...100 
(inclusive)
TargetScore number (.NET int) No   45 to set value BR->
Base Score, Target Score
should be on
Should be between 0...100
(inclusive)
StatusID
 
StatusName
number (.NET long)
 
string (.NET string)
No Pending or Overdue 
(if Due date in the past)
22
 
"pending"
Must be enabled for company.
 
Must be available for user.
 
Complete, Overdue, InReview, 
Tentative (based on role 
Allow Create Tentative Event
are not allowed
SubStatusID
 
SubStatusName
number (.NET long)
 
string (.NET string)
No null 474
 
"sub status 1"
To set value user must have role
with option Allow Edit Event 
Substatus is on
NotificationSettings NotificationSettings type  No  null    
CategoryTypeSeverities list of 
CategoryTypeSeverity
type
Yes
if template types Mandatory is on
or category Mandatory
is on
null 
(if not mandatory)
   
ExecutiveSummary string (.NET string) No null "executive summary string" Variable-length Unicode
data with a maximum 
string length of 2^30 - 1 (1,073,741,823) bytes
Recommendations string (.NET string) No null "recommendations string" Variable-length Unicode
data with a maximum 
string length of 2^30 - 1 (1,073,741,823) bytes
PartiesInvolved list of 
PartyInvolved 
type
 No null    
ClassificationIDs
 
 
ClassificationNames
list of UUID (.NET Guid)
 
list of string (.NET string)
No null [
"86b4264d-daa4-47fd-b158-cb9861c830fd",
"b7830052-9aec-4bf0-b1e6-2e7f317bb2de"
]
to set value user must have 
role where Allow manage 
Event Hours Workeds
is on
 
ConfidentialUserIDs
 
 
ConfidentialUserNames
list of number(.NET long)
 
list of string (.NET string)
No null [ 13, 22 ]  If ConfidentialUserIDs is provided then ConfidentialUserNames will be ignored.
CustomFields list of
CustomField type
Yes, if at least one 
custom field 
has option Mandatory 
and applicable for template
null 
if not mandatory
   

GpsCoordinates Type Structure:

Property Name Property Type Required?
X double-precision floating-point number
(.NET double)
Yes
Y double-precision floating-point number
(.NET double)
Yes
Z double-precision floating-point number
(.NET double)
Yes

NotificationSettings Type Structure

Property Name Property Type Required? Default Example
NotifyNow boolean
(.NET bool)
No false true
NotifyUponCompletion boolean
(.NET bool)
No false true
NonDefaultUserIDsForNowAndCompletedEmails list of numbers
(.NET long)
No null [1, 2, 3, 4]
NonDefaultUserNamesForNowAndCompletedEmails list of string
(.NET string)
No null ["user 1", "user 2"]

 

PartyInvolved Type Structure

Property Name Property Type Required? Default Example
UserID
 
UserName
number (.NET long)
 
string (.NET string)
Yes (one of two is required: 
id or name)
  11
 
"John Doe"
InvolvementTypeID
 
InvolvementTypeName
number (.NET long)
 
string (.NET string)
No null 9
 
"Involvement Type"


 
CategoryTypeSeverity

Property Name Property Type Required? Default Example
CategoryID
 
CategoryName
number (.NET long)
 
string (.NET string)
Yes if template option
cateogry -> Mandatory
is on 
null if not required 15
 
"category 1"
TypeID
 
TypeName
number (.NET long)
 
string (.NET string)
Yes if template option
type -> Mandatory
is on 
null if not required 16
 
"type 1"
SeverityID
 
SeverityName
UUID (.NET GUID)
 
string (.NET string)
No null e167aba3-1928-4268-b61d-36b725b6baee
 
"severity 1"

CustomField Type Structure

Property Name Property Type Required? Default Note
CustomFieldID
 
CustomFieldName
number (.NET long)
 
string (.NET string)
Yes (one of two is required: 
id or name)
   
Value string (.NET string) Yes   JSON string of 
custom field value. 
Format of custom fields 
values see below

 

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 not supported
XML not supported

RiskAssessment Type Structure:

Property name Property Type Required?
ConsequenceCode number (.NET integer) Yes
LikelihoodCode number (.NET integer) Yes

Gps 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

 

Usage Notes:

  • Some of response model properties have name and ID. Only one of this property should be specified. ID has highest priority. It's mean that If both properties are specified, then object will be selected by ID, name will be ignored.
  • To search object by name the system use strict string equals (case sensetive). If more that one object was found, then the system will be unable to proceed (create an event).
  • The system validates model according to configuration. Typically, the system will provide full list of validation errors. Some of validation rules are depend from Company or Template. So, if the system is unable to parse Company or Template then the system will unable to provide correct validation errors which are based on these objects.
  • Attempt to set value of property which is disabled based on BR will cause validation error.
  • All collections should not contains duplicates.
  • User must have access to all objects based on user permissions, especially to Org Unit / Entity Pair.

Example Request:

 

curl -X POST \
  https://cmo/api/events/ \
  -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWJqZWN0IjoyLCJleHAiOjE2NzEyNTI2MTUuMH0.cFq-wdxS5bLN-7WXuzCc35MUFKW465YkiyAvwcu1plo' \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache' \
  -H 'company: 2' \
  -d '{
    "companyID": 2,
    "companyName": "cmo company",
    "orgUnitID": 2,
    "orgUnitName": "cmo org unit",
    "entityID": "26DD4858-4F08-49C7-9EE2-BC93B3BAC436",
    "entityName": "cmo entity",
    "entityTypeID": 2,
    "entityTypeName": "cmo entity type",
    "templateID": 2,
    "templateName": "cmo template / form",
    "eventStartDate": "2019-02-26T08:41:52.2086077Z",
    "eventDate": "2019-02-27T08:41:52.2086077Z",
    "dueDate": "2019-02-28T08:41:52.2086077Z",
    "reporterUserID": 2,
    "reporterLogin": "cmo.user",
    "reporterName": "cmo user",
    "eventTitle": "event title",
    "gpsCoordinates": {
        "x": 1,
        "y": 1,
        "z": 0
    },
    "firstReminder": 2,
    "secondReminder": 7,
    "syncStatus": 1,
    "baseScore": 2,
    "targetScore": 2,
    "statusID": 2,
    "statusName": "cmo status",
    "subStatusID": 2,
    "subStatusName": "cmo sub status",
    "notificationSettings": {
        "notifyNow": true,
        "notifyUponCompletion": true,
        "nonDefaultUserIDsForNowAndCompletedEmails": [
            2
        ],
        "nonDefaultUserNamesForNowAndCompletedEmails": [
            "cmo user"
        ]
    },
    "categoryTypeSeverities": [
        {
            "categoryID": 2,
            "typeID": 2,
            "severityID": "C39FBB68-7028-49D3-B313-DE4DF77514E8"
        },
        {
            "categoryName": "cmo category",
            "typeName": "cmo type",
            "severityName": "cmo severity"
        }
    ],
    "executiveSummary": "executive summary value",
    "recommendations": "recommendations value",
    "partiesInvolved": [
        {
            "userName": "cmo user",
            "involvementTypeID": 2
        },
        {
            "userID": 2,
            "involvementTypeName": "cmo involvement type"
        }
    ],
    "classificationIDs": [
        "E7A3951E-6766-4D3F-99F0-1D1D053A5B18"
    ],
    "classificationNames": [
        "cmo classification"
    ],
    "confidential": true,
    "customFields": [
        {
            "customFieldID": 1,
            "value": "orange"
        },
        {
            "customFieldName": "cmo custom field",
            "value": "txt value"
        },
        {
            "customFieldID": "2",
            "value": "ajax drop down new value"
        },
        {
            "customFieldID": "3",
            "value": "[\"red\",\"green\"]"
        },
        {
            "customFieldID": "4",
            "value": "[\"2\"]"
        },
        {
            "customFieldID": "5",
            "value": "[\"1\",\"3\"]"
        },
        {
            "customFieldID": "6",
            "value": "2019-03-01T06:02:03.1676434Z"
        },
        {
            "customFieldID": "7",
            "value": "{\"consequenceCode\": 1,\"likelihoodCode\": 1}"
        },
        {
            "customFieldID": "8",
            "value": "{\"latitude\": 1,\"longitude\": 1}"
        }
    ]
}'

Example Response:

"a4afd011-3e52-4525-8b68-3d465a8c0882"

 

Error message example (in case when response model can't be processed)

 

{
    "message": "Model can't be processed due to following errors",
    "errors": [
        {
            "field": "OrgUnitID",
            "messages": [
                "System is unable to find object based on the provided id(s). (Values: 171)"
            ]
        },
        {
            "field": "EntityTypeName",
            "messages": [
                "System is unable to find object based on the provided name(s). (Values: DW_Entity_Type_1a)"
            ]
        },
        {
            "field": "EndDate",
            "messages": [
                "Mandatory but was not specified."
            ]
        }
    ]
}

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 (I mean not main company in the same cmo instance) company:
    • Authenticate as fake user which system silently creates for every company (I think it's not convinient way)
    • Specify company identifier in the request header (I think it's more convinient way), for instane for cURL it looks like: -H 'company: 42', where 42 is an identifier of a dependent company.

 

  • Was this article helpful?