Release	Date	Author	Comments
1.0	03/2024	RF	First release
1.1	04/2024	RF	Get the Timephased Custom Attribute configurationSet the Editable From date of a Timephased CA version
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 manage rate items and loading data on a given rate using the operational services.

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 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@tenantdomain 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 Customer Attributes Services

In this section, we describe the main operations available to handle the Custom Attributes as configuration (not on DataObjects) 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 Save Master Attribute Values

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

What information do we need to save master attribute values?

Slave attribute: “Country”
Slave attribute value: “Morocco”
Master attribute(s) value(s): “Africa”, “World”

In this example we will set for the “Marocco” value of the custom attribute “Country” the master value of the “Continent” custom attribute to “Africa,World”.

To set the master values to one slave attribute you should do a similar request to Triskell like this:

This is the example content request:

{

"id": 0,

"params": {

"slaveAttrId": "511",

"slaveValueId": "276",

"masterValues": "269,278"

// "masterValues": "269;278"

"objects": null

}

Note: In this example, on the masterValues parameter it is also allowed the character “;” as a separator of the values (ex: "269;278;270").

Customer can make 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.

5.1.1 Fields description

5.1.1.1 Mandatory fields

slaveAttrId: unique list custom attribute identifier (Integer). In the previous example is "Country". Can be extracted from the UI on the configuration environment:

slaveValueId: unique list custom attribute value identifier (Integer). In previous example is "Morocco". Can be extracted from the UI on the configuration environment:

5.1.1.2 Optional fields

masterValues: unique list custom attribute value identifier (Integer array). On previous example is "Africa" and “World”. Can be extracted from the UI on the configuration environment:

NOTE 1: As explained before, the masterValues parameter is optional, but if not sent, it has one specific behavior on the way the service saves the data. In this case (if not sent or empty value), it will delete all the master custom attribute values from the slave custom attribute value.

NOTE 2: To be also clear the way the service saves the data, it always saves the values from scratch, I mean, as it was from the first time. This means that all master customer attribute values must be sent on the call. For example, if it is desired to add one new master customer attribute value to the slave one, and keep the old ones, the old ones need to be sent also, other wise they will be removed.

5.2 Get Timephased Custom Attribute configuration

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

What information do we need to get the configuration of a Timephased CA?

Timephased Custom Attribute: “Cost Plan”

In this example we will get the full configuration for the “Cost Plan” timephased custom attribute.

To get the configuration you should do a similar request to Triskell like this:

This is the example content request:

{

"id": 0,

"params": {

"tpaCustomAttrId": "363"

"objects": null

}

This is one example of the answer for the request above:

{

"authash": "03663e556a63170e8fe3b40667f6e09f",

"executime": 33913000,

"messages": [],

"message": null,

"resultType": 1,

"data": {

"updatedBy": 102,

"active": true,

"isHeadcount": false,

"mode": 1,

"archived": false,

"calendarId": 2,

"isMultiline": false,

"versions": [

{

"updatedBy": 102,

"active": true,

"readOnly": false,

"decimalPrecision": 1,

"includeRollup": true,

"inputLevel": 4,

"archived": false,

"visualLevel": 2,

"lastmodified": "2024-04-08 17:56:43",

"lockedUntil": "2024-04-01",

"name": "Forecast",

"id": 8,

"defaultVersion": false

{

"updatedBy": 102,

"active": true,

"readOnly": false,

"decimalPrecision": 2,

"includeRollup": true,

"inputLevel": 4,

"archived": false,

"visualLevel": 2,

"lastmodified": "2023-10-14 09:26:57",

"lockedUntil": null,

"name": "Budget - Proposed",

"id": 18,

"defaultVersion": false

{

"updatedBy": 102,

"active": true,

"readOnly": false,

"decimalPrecision": 1,

"includeRollup": true,

"inputLevel": 4,

"archived": false,

"visualLevel": 2,

"lastmodified": "2024-03-26 14:58:45",

"lockedUntil": null,

"name": "Budget - Allocated",

"id": 7,

"defaultVersion": true

{

"updatedBy": 102,

"active": true,

"readOnly": false,

"decimalPrecision": 2,

"includeRollup": true,

"inputLevel": 4,

"archived": false,

"visualLevel": 2,

"lastmodified": "2023-10-14 09:26:57",

"lockedUntil": null,

"name": "Project Rollup",

"id": 16,

"defaultVersion": false

{

"updatedBy": 102,

"active": true,

"readOnly": false,

"decimalPrecision": 1,

"includeRollup": true,

"inputLevel": 4,

"archived": false,

"visualLevel": 2,

"lastmodified": "2023-10-14 09:26:57",

"lockedUntil": null,

"name": "Actuals",

"id": 9,

"defaultVersion": false

}

"lastmodified": "2014-03-20 15:50:19",

"name": "Cost Plan",

"isCurrency": true,

"aditionalComments": false,

"attributes": [

{

"sequence": 1,

"name": "Region",

"id": 346

{

"sequence": 2,

"name": "Cost Type",

"id": 362

}

"id": 363

"description": null,

"id": 0,

"i18NParams": [],

"i18NMessageId": "",

"success": true,

"ret_i18n_code": "",

"ret_i18n_params": [],

"ret_count": 0

}

5.2.1 Fields description

5.2.1.1 Mandatory fields

tpaCustomAttrId: unique timephased custom attribute identifier (Integer). In the previous example is "Cost Plan". Can be extracted from the UI on the configuration environment:

5.2.1.2 Optional fields

5.3 Change Editable From of a Timephased Version

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

What information do we need to change the Editable From date?

Timephased Custom Attribute: “Cost Plan”
Version: “Forecast”
Date: 01/04/2024

In this example we will set the date of the Editable From field to 01/04/2014, for the version Forecast of the timephased custom attribute “Cost Plan”.

To set the date on the Editable From field you should do a similar request to Triskell like this:

This is the example content request:

{

"id": 0,

"params": {

"tpaCustomAttrId": "363",

"tpaVersionId": "8",

"lockedUntil": "2024.04.01"

"objects": null

}

To see if the Editable From data was edited you can check on Triskell.

5.3.1 Fields description

5.3.1.1 Mandatory fields

tpaCustomAttrId: unique timephased custom attribute identifier (Integer). In the previous example is "Cost Plan". Can be extracted from the UI on the configuration environment:

tpaVersionId: unique timephased custom attribute version identifier (Integer). In previous example is "Forecast". Can be extracted from the UI on the configuration environment:

5.3.1.2 Optional fields

lockedUntil: unique Date in the day format (String). In previous example is "2024.04.01". The Date must be in the ISO format to work (YYYY.MM.DD), without hours, minutes, and seconds. NOTE: If the date parameter it is not send or send with empty value, the value of the Editable From date will be deleted (set to NULL).

6 Auxiliary Services to get data

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

6.1 N/A

N/A

Related to

3.1 Login Service

3.2 Logout Service

5.1.1.1 Mandatory fields

5.1.1.2 Optional fields

5.2.1.1 Mandatory fields

5.2.1.2 Optional fields

5.3.1.1 Mandatory fields

5.3.1.2 Optional fields

6.1 N/A

Related articles