Creating Standalone Actions via REST API

Last updated
Save as PDF

Creating Standalone Actions via REST API

REST API for Actions lets the user create/update/delete/change statuses of actions automatically without using CMO interface in a web browser or mobile app. The user can create activities without logging into the CMO account and doesn’t need to create one action after another manually.

The user must have supporting software that helps in integrating CMO applications for action creation to user applications where an action can be created and related data can be pulled.

REST API Overview for Action

S.No	Request Method	Description	URL	Example	Request Response
1	POST	Creates a standalone Action in CMO, and fills in all the Action fields with the values specified in the API request.	[cmo-base-url]/api/actions	POST [cmo-base-url]/api/actions	POST Request Response
2	PUT	Updates fields of an existing Action in CMO.	`[cmo-base-url]/api/actions/{action-id}`	`PUT [cmo-base-url]/api/actions/14b44c76-b1d4-4df1-84b6-2f2f583ae67d`	PUT Request Response
3	GET	Returns the details of an Action from CMO.	`[cmo-base-url]/api/actions/{action-id}`	`GET [cmo-base-url]/api/actions/14b44c76-b1d4-4df1-84b6-2f2f583ae67d`	GET Request Response
4	DELETE	Removes an Action from CMO.	`cmo-base-url]/api/actions/{action-id}`	`DELETE [cmo-base-url]/api/actions/14b44c76-b1d4-4df1-84b6-2f2f583ae67d`	DELETE Request Response

Note: Click on the links of the request method in the Request Response column to navigate to the respective sections.

1. Request Responses

1.1 POST Method

Note: The Rest API for actions lets the user to create single action creation. This API does not support for creating scheduled actions.

1.1.1 Prerequisites

The user performing the request has to have 'Allow Create via API' role permission enabled. Login to the CMO application > Go to Admin > Roles > Action Permissions > Check in Allow Create via API check box to enable the permission.

1.1.2 API endpoint details

To invoke the API, the user must perform a Web request described as follow:

Web Request Method: POST

URL: [cmo-base-url]/api/actions

For example: POST [cmo-base-url]/api/actions

The API Request body has to be in JSON format. See the following example:

1 {

2 "orgUnitName": "North America Operations,

3 "entityName": "Head Office",

4 "actionCategoryName": "Emergency Response",

5 "actionText": "Fix the pipes ",

6 "guidanceText": "Guidance Text for Action Created via public API #3",

7 "responsibleUserName": "Dan Johnson",

8 "carbonCopyEmail": "test@example.com",

9 "actionPriorityName": "High",

10 "gpsCoordinates": {"X": 1, "Y": 2, "Z": 3},

11 "dueDate": "2021-07-02T13:59:59.997Z",

12 "hoursTaken": 15,

13 "actionValue": 25,

14 "progress": 33,

15 "geocortexFeature": null,

16 "residualRisk": { "consequenceCode": 1, "likelihoodCode": 1 },

17 "inherentRisk": { "consequenceCode": 2, "likelihoodCode": 2 },

18 "attachmentRequired": true,

19 "confidential": false,

20 "customFields": [{"customFieldName": "happiness", "value": "very high score"}]

21 }

Instead of the following fields, alternative fields with Id suffix can be used in the API request body.

"orgUnitName"
"entityName"
"actionCategoryName"
"actionPriorityName"
"customFieldName"

Instead of passing the original API request body

1 {

2 "orgUnitName": "Albama",

3 "entityName": "Some Entity Name",

4 ...

5 }

The following API request body can be passed by

1 {

2 "orgUnitId": 12480,

3 "entityId": "0656ef56-f3e2-418b-9f47-1de3c889dd6f",

4 ...

5 }

There are two alternatives for the field "responsibleUserName"

"responsibleUserId"
"responsibleUserLogin"

To pass no-risk value for "residualRisk" of "inherentRisk" - there are 2 ways:

1. Pass it with “likelihoodCode” and “consequenceCode” being

1 {

2 …,

3 “residualRisk”: {

4 “consequenceCode”: -1,

5 “likelihoodCode”: -1

6 },

7 …

8 }

2. Just pass null:

1 {

2 ...,

3 "residualRisk": null,

4 ...

5 }

"dueDate" must be a timestamp in ISO UTC format. The timestamp value should point to the end of the desired Action Due Date (to anywhere within the last second of that date to be exact). This considers the Time Zone configured for the company (in Admin / Business Rules section).

For example, to create an Action, Action Due Date must be passed in 'India Standard Time - (UTC+05:30) Chennai, Kolkata, Mumbai, New Delhi'. This means that Action Due Date for July 22nd, 2021 should be in the following format (with 05:30 offset from UTC):

2021-07-22T18:29:59.997Z

1.1.3 API Response

In case of successful execution, the API responds with HTTP 200 OK response code and the created Action ID JSON string in the response body:

1"68579fa4-a2bd-4ae4-b041-76c08dc4699b"

In case if action cannot be created due to invalid data passed to the API - it responds with HTTP 400 Bad Request response code and the error detail in JSON format in the response body:

2 "message": "Model can't be processed due to following errors",

3 "errors": [

4 {

5 "field": "OrgUnitName",

6 "messages": [

7 "System is unable to find object based on the provided name(s). (Values: Albama)"

8 ]

9 }

10 ]

11}

In case if user performing the API and the call lacks the role permission to create Actions within CMO - the API responds with HTTP 403 Forbidden response code.

1.2. PUT Method

1.2.1 Prerequisite

The user performing the request has to have 'Allow Create via API' role permission enabled. Login to CMO application > Go to Admin > Roles > Action Permissions > Check in Allow Edit via API check box to enable the permission.

1.2.2 API endpoint details

To invoke the API - perform a Web Request as described below:

Web request method: PUT

URL: [cmo-base-url]/api/actions/{action-id}

For example: PUT [cmo-base-url]/api/actions/14b44c76-b1d4-4df1-84b6-2f2f583ae67d

Request body has to be in JSON format. See the example below:

2 "orgUnitName": "Albama",

3 "entityName": "ActionEntity",

4 "actionCategoryName": "Act",

5 "actionText": "Action Updated via public API #3",

6 "guidanceText": "Guidance Text for Action Updated via public API #3",

7 "responsibleUserName": "Dan Johnson",

8 "carbonCopyEmail": "test@example.com",

9 "actionPriorityName": "High",

10 "gpsCoordinates": {"X": 1, "Y": 2, "Z": 3},

11 "dueDate": "2021-07-02T13:59:59.997Z",

12 "hoursTaken": 15,

13 "actionValue": 25,

14 "progress": 33,

15 "geocortexFeature": null,

16 "residualRisk": { "consequenceCode": 1, "likelihoodCode": 1 },

17 "inherentRisk": { "consequenceCode": 2, "likelihoodCode": 2 },

18 "attachmentRequired": true,

19 "confidential": false,

20 "customFields": [{"customFieldName": "happiness", "value": "very high score"}]

21}

Instead of any of the following fields the alternative field with Id suffix can be passed:

"orgUnitName"
"entityName"
"actionCategoryName"
"actionPriorityName"
"customFieldName"

so instead of passing:

2 "orgUnitName": "Albama",

3 "entityName": "Some Entity Name",

4 ...

the following can be passed:

2 "orgUnitId": 12480,

3 "entityId": "0656ef56-f3e2-418b-9f47-1de3c889dd6f",

4 ...

For the field "responsibleUserName" there are 2 alternatives:

"responsibleUserId"
"responsibleUserLogin"

To pass no-risk value for "residualRisk" of "inherentRisk" - there are 2 ways:

Pass it with "likelihoodCode" and "consequenceCode" being -1, like:

2 ...,

3 "residualRisk": {

4 "consequenceCode": -1,

5 "likelihoodCode": -1

6 },

7 ...

or just pass null:

2 ...,

3 "residualRisk": null,

4 ...

For example, to create an Action, the Action Due Date must be passed in 'India Standard Time - (UTC+05:30) Chennai, Kolkata, Mumbai, New Delhi'. This means that Action Due Date for today (July 22nd, 2021) should be like the following (with 05:30 offset from UTC):

2021-07-22T18:29:59.997Z

1.2.3 API Response

In case of successful execution, the API responds with HTTP 200 OK response code with empty response body.

In case if action cannot be updated due to invalid data passed to the API - it responds with HTTP 400 Bad Request response code and the error detail in JSON format in the response body:

2 "message": "Model can't be processed due to following errors",

3 "errors": [

4 {

5 "field": "OrgUnitName",

6 "messages": [

7 "System is unable to find object based on the provided name(s). (Values: Albama)"

8 ]

9 }

10 ]

11}

In case if the user performing the API and the call lacks the role permission to update Actions within CMO - the API responds with HTTP 403 Forbidden response code.

1.3. GET Method

1.3.1 API endpoint details

To invoke the API - perform a Web Request, described below:

Web request method: GET

URL: [cmo-base-url]/api/actions/{action-id}

For example: GET [cmo-base-url]/api/actions/14b44c76-b1d4-4df1-84b6-2f2f583ae67d

1.3.2 API Response

In case of successful execution, the API responds with HTTP 200 OK response code with the requested Action Details in JSON format in the response body:

2 "id": "14b44c76-b1d4-4df1-84b6-2f2f583ae67d",

3 "uniqueID": "6142",

4 "actionText": "Action Created via public API #4 asd",

5 "status": {

6 "code": 1,

7 "name": "Pending"

8 },

9 "guidanceText": "Guidance Text for Action Created via public API #4",

10 "carbonCopyEmail": "test@example.com",

11 "orgUnit": {

12 "id": 12480,

13 "name": "Albama"

14 },

15 "entity": {

16 "id": "3c3e7dd6-469c-4ca6-8962-0c0bc0636ed6",

17 "name": "Abs new test entity"

18 },

19 "category": {

20 "id": 2233,

21 "name": "Act"

22 },

23 "priority": {

24 "id": "7cc13288-e9f9-46d4-bfc9-443e3ad00c9b",

25 "name": "High"

26 },

27 "assignorUser": {

28 "id": 20518,

29 "firstName": "Dan",

30 "lastName": "Johnston",

31 "loginName": "superadmin",

32 "email": "pavel.pargachev@mitratech.com"

33 },

34 "responsibleUser": {

35 "id": 20518,

36 "firstName": "Dan",

37 "lastName": "Johnston",

38 "loginName": "superadmin",

39 "email": "pavel.pargachev@mitratech.com"

40 },

41 "createdDateTime": "2021-06-29T06:57:37.233Z",

42 "dueDate": "2021-07-02T13:59:59.997Z",

43 "verifications": [],

44 "gpsCoordinates": {

45 "x": -30.442976,

46 "y": 136.849222

47 },

48 "actionValue": 25.0,

49 "hoursTaken": 15,

50 "progress": 90,

51 "residualRisk": {

52 "consequenceCode": -1,

53 "likelihoodCode": -1

54 },

55 "inherentRisk": {

56 "consequenceCode": 2,

57 "likelihoodCode": 2

58 },

59 "customFields": [

60 {

61 "customFieldID": 3590,

62 "customFieldName": "happiness",

63 "customFieldTypeName": "Text Box",

64 "value": "not so high score"

65 }

66 ]

67}

In case if the user performing the API and the call lacks the role permission to update Actions within CMO - the API responds with HTTP 403 Forbidden response code.

1.4. DELETE Method

1.4.1 Prerequisite

The user performing the request has to have 'Allow Create via API' role permission enabled. Login to the CMO application > Go to Admin > Roles > Action Permissions > Check in Allow Delete via API check box to enable the permission.

1.4.2 API endpoint details

To invoke the API - perform a Web Request, described below:

Web request method: DELETE

URL: cmo-base-url]/api/actions/{action-id}

For example: DELETE [cmo-base-url]/api/actions/14b44c76-b1d4-4df1-84b6-2f2f583ae67d

1.4.3 API Response

In case of successful execution, the API responds with HTTP 200 OK response code with an empty response body.

In case if action cannot be deleted due to some restriction unrelated to user permissions - it responds with HTTP 400 Bad Request response code and the error detail in JSON format in the response body:

2 "message": "You cannot delete Actions created by Event Workflow"

In case if user performing the API and the call lacks the role permission to update Actions within CMO - the API responds with HTTP 403 Forbidden response code.

2. Authorization

Like any other CMO Public API, all the following types of request authorization are supported

JWT Token Authorization
Mutual Certificate Authorization
Public API Token Authorization

2.1 JWT Token Authorization

The user sends the login name and password to the specific endpoint of the CMO API to retrieve the token. Then the user can use this token to call REST APIs in CMO which support it.

1. Request a JWT token, by calling the JWT Token API endpoint

Web Request Method: POST
URL: [cmo-base-url]/api/token

JSON request body:
{
"login": "<put login here>",
"password": "<put password here>"
}

2. In case of successful authentication, the JWT Token API endpoint will respond with HTTP 200 OK response code and with the newly generated JWT token in JSON string Response Body

"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWJqZWN0IjoyMDUxOCwiZXhwIjoxNjI4MDEyNDg0LjB9.nzLWuRDYKo9-BWwYOxOLeNnVRAzQL_qEVPObI6vMrcE"

3. Add the JWT token to the Authorization HTTP Request Header (using the Bearer scheme) while performing a call to the desired endpoint of CMO API, so the header looks like this:

Authorization: Bearer <put the JWT token here>

Here is a complete example:
Method: POST
URL: [cmo-base-url]/api/actions

HTTP Request Headers:
Content-Type: application/json
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWJqZWN0IjoyMDUxOCwiZXhwIjoxNjI4MDEyNDg0LjB9.nzLWuRDYKo9-BWwYOxOLeNnVRAzQL_qEVPObI6vMrcE
...

JSON HTTP Request Body:
{
"orgUnitName": "North America Operations",
"entityName": "Head Office",
...
}

It can be turned on/off in the web.config and set the token's expiration time (default 20mins).

1.

2. <add key="Authentication.Jwt.Enabled" value="true"/>

3.

4. <add key="Authentication.Jwt.Secret" value=""/>

5.

6. <add key="Authentication.Jwt.Expire" value="2000000"/>

Make sure that "Secret" is not empty. Use keys for the secret values.

Note: Do not share keys between environments. Every environment should have own key.

2.2 Mutual Certificate Authorization

It can be turned on/off in the web.config. To use this authentication type appropriate configuration should be applied to the web.config (client cert mappings and so on...)

1. <add key="Authentication.Mutual.Enabled" value="True" />

2.

3. <add key="Authentication.Mutual.RootCertificateThumbprint" value="" />

4.

5. <add key="Authentication.Mutual.TrustedClientThumbprints" value="" />

2.3 User’s Token Authorization

It is a static token which is stored in the Users table. It can be set/re-set only manually via DB using SQL script. This is the default auth type and it will be used only if JWT and Mutual authentication types are turned off.

Steps to use Static user API Token:

1. Execute SQL request directly on the CMO database to update ApiToken field on the Users table for the desired user account.
Example of SQL request to update CMO User static access token:

UPDATE Users SET ApiToken = '121218409EB643899FDFA11FE54BF5746B88C948D7E746BB9C7986CB88405F9B780D2474742C42919B15B4753732D7F3' WHERE UserID = 20518

UserID is the internal user identifier in the CMO database. Static API Token can be any string up to 200 characters long. It's recommended to choose a long string of random characters, that is impossible to guess for malicious actor.

2. Add the Static API Token to Authorization HTTP Request Header (using the Bearer scheme) while performing a call to the desired endpoint of CMO API, so the header looks like this:

Authorization: Bearer <put the Static API Token here>

Here is a complete example:
Method: POST
URL: [cmo-base-url]/api/actions

HTTP Request Headers:
Content-Type: application/json
Authorization: Bearer 121218409EB643899FDFA11FE54BF5746B88C948D7E746BB9C7986CB88405F9B780D2474742C42919B15B4753732D7F3
...

JSON HTTP Request Body:
{
"orgUnitName": "North America Operations",
"entityName": "Head Office",
...
}