Release	Date	Author	Comments
1.0	11/2019	RF	First release
1.1	12/2019	RF	Add the Read Comments with roles
1.2	03/2026	RF	Update document to Bruno software

2 Introduction

Several REST web services are provided allowing tenant and customers to interact with Triskell virtually from any environment/platform. This document describes how to use the comments of a dataobject.

Usually, Web services are designed to manage small set of data.

If you are not sure they will cover your requirements please contact us at :

support@triskellsoftware.com.

In this document there are some examples about how to send information to Triskell using Bruno plug-in, from Bruno Software. You can get Bruno for free here. Then you just need to import the attached file "TriskellAPI.yml" and the file “NextRelease-environment.json”. The last file is used to set environment variables, so it can be easily tested on different environments.

It's very important to test your code on the Nextrelease environment before delivering it on the production environment (https://nextrelease.triskellsoftware.com/triskell/). In this document examples given are using Localhost as testing environment.

Some internal id's can be different between testing and production environments. Please review the hardcoded id's before delivering it on production environment.

3 Authentication

From the authentication point of view, there are two kinds of web services on Triskell: stateful and stateless.

Most of the REST services provided are Stateful, which means that interacting with them requires a login first.

On the other hand, Stateless services will do a user authentication on every call.

Stateless services are intended to be used from clients not capable of managing a session cookie to maintain a dialog with the server.

In this document, only Stateless services will be denoted, most of the services being Stateful by default.

Two services are provided to log in and log out of Triskell.

Stateless services must provide their authentication parameters as HTTP Headers on every service call.

3.1 Login Service

The login service must be invoked before any other stateful Triskell web service call. It receives a user identifier and a password as URL parameters.

URL

https:// SERVER /triskell/service/rest/login/user/{userId}/passwd/{pass}

HTTP Method

GET

URL Parameters

{ userId }: String containing user identifier as ‘user@tenant.com’ URI encoded

{ pass }: String containing a Base64 encoded MD5 (normal user) or SHA256 (rest user) hash of the password

Note: the user used to make the login need have the right privileges/roles in the Triskell to use/change the data. Otherwise it will not be possible to use/change the data and will return an error of missing privileges.

When login is successful it returns a HTTP response code ‘200 – OK’An authentication failure will return HTTP response code ‘401 – UNAUTHORIZED’

Example:

3.2 Logout Service

Logout service provided for closing the session at the server.

URL	URL: https:// SERVER /triskell/service/rest/logout
HTTP Method	GET

Example:

Don't forget to close your session when finishing your REST conversation

4 Service Proxies

Service Proxies are a simple way of executing remote procedure calls Operation services.

Requests and responses are exchanged as JSON objects with the clients, to enhance easiness and interoperability.

The proxy input object DataRequest, is compound of the following properties:

Id : numerical identifier
Params: A simple JSON object containing only primitive type properties.
Objects: Array of JSON objects of any type.

These properties must be present into the object being it used or not.

Example of DataRequest:

{

'id' : 1 ,

'params' : {

"param_1":"A",

"param_2":2

} ,

'objects' : [

{"NAME":"OBJECT_1"},

{"NAME":"OBJECT_2"}

]

}

The proxy output object Result, is compound of the following properties:

success: Boolean indicating successfulness of the request.
message: Error description.
resultType: Numerical identifier, error severity ( 1-OK, 2–Warning, 3-Error)
data: a String or a JSON object
id: a numerical identifier
authash: session identifier
executime: service execution time in nanoseconds
i18NParams and i18NMessageId: used on internationalized error message

Example of DataResult :

{

"authash":"dd06d7c94cd9a73f62b45c5b54247bce",

"executime":10997027,

"success":true,

"message":null,

"resultType":1,

"data":"Hello world !!!",

"id":0,

"i18NParams":[],

"i18NMessageId":""

}

4.1 Operation Service Proxy

This is a Web Service to execute operations on a Triskell OperationService.

An OperationService groups related functionalities allowing to access then by his Operation Name.

OperationServiceProxy has two implementations, stateful and stateless.

4.1.1 Stateful Operation Service Proxy

Any stateful service requires a Login to be done before submitting any request to it.

4.1.2 WS Operation execute

Execute a service operation call. DataRequest is sent attached to the body of the HTTP request.

URL	URL: https:// SERVER /triskell/service/rest/proxy/operation/execute/{serviceName}/{operationName}
HTTP Method	POST
Content-Type Header	application/json
URL Parameters	{serviceName} : String containing the name of the service to be called {operationName} : String containing the Operation name

4.1.3 Stateless Operation Service Proxy

This web service does not require doing a previous Login on Triskell, a user authentication is done on every request.

4.1.4 WS Operation execute

Execute a service operation call. DataRequest is sent as a URL parameter.

URL	https:// SERVER /triskell/service/rest/proxy/operation/execute/{serviceName}/{operationName}/{payload}
HTTP Method	GET
Content-Type Header	X-Account-Name Header: Optional, username@tenant.domain X-API-Key Header: Optional
URL Parameters	{serviceName} : String containing the name of the service to be called {operationName} : String containing the Operation name {payload} : JSON DataRequest Object encoded in Base64

5 DataObject Comments Usage

In this section, we describe the main operations available to handle the comments in one dataobject in Triskell using the existing Stateful services for the most basic use of case. In this document, we are using examples from a standard configuration at test.com.

5.1 Create comment

To use this call, the user logged don’t need to have the Configurator role in Triskell, also we need get some information from your instance to make it work properly.

Version 1

What information do we need to create a comment?

Dataobject to insert the Comment: "PRJ 006"
Topic of the Comment: "The first"
Content of the Comment: "This is the content of the first comment”
Visibility of the Comment: “Public”

We need to extract all this information from Triskell. Some information can be taken directly from your Triskell instance using the UI and, in some cases, we need to make a request using an operational service to get data from a stored selector report.

This is a request example:

This is the example content request:

{

"id": 0,

"params": {

"dataObjectId": "1069",

"ownerUserId": "102",

"publicComment": true,

"rolesCombo": "",

"topic": "One nice Topic",

"content": "This is also a very nice Content delivered by REST"

} ,

"objects": null

}

Customer can do more than one request on the same REST conversation depending on your functional needs. This feature should not be used to insert big data volumes because. During the REST conversation Triskell users can get blocked processing the request, so we suggest using it with common sense in terms of data volume and scheduling. Triskell will limit the number of requests by day in the future to avoid collapsing the server, so please take this in account when developing your interfaces.

To see if the Comment was added in the Dataobject you can check on Triskell.

Version 2

What information do we need to create a comment?

Dataobject to insert the Comment: "PRJ 006"
Topic of the Comment: "The first"
Content of the Comment: "This is the content of the first comment”
Visibility of the Comment: “Project Manager, Project Sponsor”

This is a request example:

This is the example content request:

{

"id": 0,

"params": {

"dataObjectId": "1069",

"ownerUserId": "102",

"publicComment": false,

"rolesCombo": "51,52",

"topic": "One nice Topic",

"content": "This is also a very nice Content delivered by REST"

} ,

"objects": null

}

To see if the Comment was added in the Dataobject you can check on Triskell.

5.1.1 Fields description

5.1.1.1 Mandatory fields

dataObjectId: unique dataobject instance identifier (Integer). In the previous example is "PRJ 006". It requires making a request to Triskell to get it.
ownerUserId: unique user identifier (Integer). In previous example is " ** Global Configurator". Can be extracted from the UI on the configurator environment:

publicComment: Boolean value true/false (if false the field rolesCombo must be provided).
topic: String value with the text desired.

5.1.1.2 Optional fields

rolesCombo: unique role instance identifier (Integer). In the previous example are "Project Manager, Project Sponsor". Can be extracted from the UI on the configuration environment:

content: String value with the text desired.

5.2 Update a comment

To use this call, the user logged don’t need to have the Configurator role in Triskell, also we need get some information from your instance to make it work properly.

What information do we need to update one Comment in a Dataobject?

Dataobject: "PRJ 006"
Topic: "The first v2"
Content: "This is the content of the first comment v2”
Visibility: “public”

In this example we will change the previous created Comment (version 2) with new values in the listed before. Note that we will change the visibility from “private” to “public”, but the opposite is also possible with the addiction of the rolesCombo.

To change the comment, you should do a similar request to Triskell like this:

This is the example content request:

{

"id": 0,

"params": {

"dataObjectId": "1069",

"commentId": "239",

"publicComment": true,

"topic": "One nice Topic v2",

"content": "This is also a very nice Content delivered by REST v2"

} ,

"objects": null

}

To see if the Comment was updated in the Dataobject you can check on Triskell.

5.2.1 Fields description

5.2.1.1 Mandatory fields

dataObjectId: unique dataobject instance identifier (Integer). In the previous example is "PRJ 006". It requires making a request to Triskell to get it.
commentId: unique comment identifier (Integer). In previous example is the value returned by the call of the “Creation Comment”. If it’s not saved, it requires making a request to Triskell to get it.
publicComment: Boolean value true/false (if false the field rolesCombo must be provided).
topic: String value with the text desired.

5.2.1.2 Optional fields

rolesCombo: unique role instance identifier (Integer). In the previous example are "Project Manager, Project Sponsor". Can be extracted from the UI on the configuration environment:

content: String value with the text desired.

5.3 Delete a comment

To use this call, the user logged don’t need to have the Configurator role in Triskell, also we need get some information from your instance to make it work properly.

What information do we need to delete one Comment in a Dataobject?

Dataobject: "PRJ 006"
Comment: "The first v2"

In this example we will delete the previous created and updated Comment (version 2) with new values in the listed before. Note that the delete will delete also all the visibility associated to the Comment if they exist.

To delete the comment, you should do a similar request to Triskell like this:

This is the example content request:

{

"id": 0,

"params": {

"dataObjectId": "1069",

"commentId": "239"

} ,

"objects": null

}

To see if the Comment was deleted in the Dataobject you can check on Triskell.

5.3.1 Fields description

5.3.1.1 Mandatory fields

dataObjectId: unique dataobject instance identifier (Integer). In the previous example is "PRJ 006". It requires making a request to Triskell to get it.
commentId: unique comment identifier (Integer). In previous example is the value returned by the call of the “Creation Comment”. If it’s not saved, it requires making a request to Triskell to get it.

5.4 Read comments

To use this call, the user logged don’t need to have the Configurator role in Triskell, also we need get some information from your instance to make it work properly.

Version 1

What information do we need to get all comments of a Dataobject?

Dataobject: "PRJ 006"

This is a request example:

This is the example content request:

{

"id": 0,

"params": {

"dataObjectId": "1069"

} ,

"objects": null

}

Customer can do more than one request on the same REST conversation depending on your functional needs. This feature should not be used to load big data volumes because. During the REST conversation Triskell users can get blocked processing the request, so we suggest using it with common sense in terms of data volume and scheduling. Triskell will limit the number of requests by day in the future to avoid collapsing the server, so please take this in account when developing your interfaces.

Version 2

What information do we need to get one(s) comment(s) of a Dataobject?

Dataobject: "PRJ 006"
Role: “Project Manager”
Topic: "One nice Topic v3"

This is a request example:

This is the example content request:

{

"id": 0,

"params": {

"dataObjectId": "1069",

"roleId": "51",

"topic": "One nice Topic v3"

} ,

"objects": null

}

5.4.1 Fields description

5.4.1.1 Mandatory fields

dataObjectId: unique dataobject instance identifier (Integer). In the previous example is "PRJ 006". It requires making a request to Triskell to get it.

5.4.1.2 Optional fields

roleId: unique role instance identifier (Integer). In the previous example are "Project Manager ". Can be extracted from the UI on the configuration environment:

topic: String value with the text of the Comment topic to find.

NOTE: these 2 optional fields can be combined to make the filter more specific. Can be use one of them or both together, just like the need of the filter.

5.5 Reply to a comment

This option and functionality it’s not implemented yet. For now, only the basic usage of the Comments are implemented to reply to the general usage of the Comments in Triskell.

If in future this feature will be needed, it can be implemented.

5.6 Close/Open a comment

This option and functionality it’s not implemented yet. For now, only the basic usage of the Comments are implemented to reply to the general usage of the Comments in Triskell.

If in future this feature will be needed, it can be implemented.

5.7 Read comment reply’s

This option and functionality it’s not implemented yet. For now, only the basic usage of the Comments are implemented to reply to the general usage of the Comments in Triskell.

If in future this feature will be needed, it can be implemented.

6 Auxiliary Services to get data

In this section it will be explained how to extract data required to call main services.

6.1 Get dataObjectId

In this section we describe how to get the dataObjectId identifier from Triskell. Triskell allows extract data from your instance using reports. You need a stored selector to build your report.

First, we need to get the Object of your dataObject to get: