CoreTRM allows external systems to interface with it. External systems are able to request or update CoreTRM using the API of CoreTRM provided they have the necessary security access.

There is a built-in API builder in CoreTRM to help users generate API request urls based on data needed and filter criteria.

The data return can be either in JSON or CSV format.

To access the API Builder for generating API requests, go to System Admin and then to the API Builder->API Requests tab.

Example of Sort Item Refs

Example of Summary Item Refs

Example of Grouping Filter

Testing API Request using Postman

API Requests

To start building API request, from API Requests view:

1. Click on to create a new line.
2. In API Request Name enter the name for the API request.
3. In Object select the base object from which the data should be retrieved from. This is similar to writing an SQL query where you would choose the most appropriate table to start from.
4. In Per Page Num indicated how many data results to be displayed per page. This is defaulted to 12 per page.
5. In Page Num indicate the page number to be display. This is defaulted to page 1.
6. In Return CSV check the box if the data return should be in CSV format.
7. In Item Refs select the Item Refs to be included as part of the data to be retrieve from the API.

*Detail steps on how to select Item Refs. can be found here.*

8. In Sort Item Refs indicate if the results should be sorted by selected Item Refs.

*Example of Sort Item Refs can be found here.*

9. In Summary Item Refs indicate if the results should be summarized by selected Item Refs.

*Example of Summary Item Refs can be found here.*

10. In Include Key Items? check the box if Key Items will be included in the data results.
11. In Include Foreign Key Items? check the box if Foreign Key Items will be included in the data results.
12. In Include TimeStamp? check the box if the Timestamp item will be included in the data results.
13. In Include Additional Meta? check the box if additional meta will be included in the data results.

The following additional meta will be included in the data results: "isKeyItemInd","isTimeStampItemInd","canChangeOnUpdateInd","canIncludeOnInsertInd","canIncludeOnDeleteInd".

14. Click to confirm creation.
15. To edit API requests details after creation Click to edit.

Use the Filters panel to add filters to the request:

1. Click on to create a new line.

2. In Order indicate the order number of the filter criteria.

3. In And Or if there is more than 1 filter criteria, "And" or "Or" can be used to indicate the filter crieria relationship.

4. In Left Brackets left brackets should be included when there are "Or" conditions present.

   

5. In Left Item Ref. select the Left Item Ref to be used for this filter criteria.

6. In Condition select the condition to be used for this filter criteria.

   *Conditions available are "contains", "equals", "greater than", "greater than or equal to", "in", "less than", "less than or equal to", "not contains", "not equals" and "not in".

7. In Right Item Ref. select the Right Item Ref if the condition is comparing with another Item Ref value. Either Right Item Ref. or Right Value is to be used.

8. In Right Value enter a Right Value if the condition is to compare with a fixed value. Either Right Item Ref. or Right Value is to be used.

9. In Right Brackets right brackets should be included when there are "Or" conditions present.

10. In Grouping Filters? check the box if the filter criteria is involved a function that requirs grouping. Example of functions: fnSum, fnMax, fnMin, etc. Grouping filters work in a similar way to SQL Having clauses.

    *Example of Grouping Filters can be found here.*

11. In Active? check the box if this line of filter criteria is to be active.

12. Click to confirm creation.

13. To edit filter details after creation, Click to edit.

After the required data and filters are indicated in API requests and Filters view, CoreTRM will generate the appropriate syntax and a API URL that can be used to retrieve the data from the system.

The API URL can be used by external systems as the API End Point to call the API in order to retrieve data from CoreTRM.

Once the API URL is created as above click on to preview the data results as shown below.

As part of the JSON data results the system will provide additional information on the Item Refs. Below is the default information provided.

In addition, as part of the JSON data results, the system will also provide information on paging as shown below.

Item Refs

To start selecting Item Refs to be included in the data results:

1. From the Item Refs click on to open the Item Refs browser pop up.
2. From the "Object" section, select the object from which the Item Ref you wish to be included in the API data results. After selecting the "Object", from the "Object ITem Refs" section, select the Item Refs that you wish to use.

For Example, below we are selecting the contractdate item ref from Contract object.



3. To add more Item Refs click on to add the next item ref.

For Example, below we are selecting the contractreference item ref from Contract object.



4. It is also possible to add item refs from other objects other than the base object that you have selected in API Requests -> Object column from above as long as the destination object has a relationship with the base object.

For Example, below we are selecting counterpartyname item ref from Counterparty object.

a. From the "Object" section select Counterparty.

b. From the "Object Item Refs." section select Counterparty Name.



5. Once all the Item Refs are selected click on to confirm the selection.

More information about Item Refs can be found in Understanding Item References.

Item Refs Using Functions

In addition, API functions can also be used as part of the Item Refs selection.

For example, to include the fnIsNull function. If contract description is null, True: set value to "Description is empty" and False: set value to contract description.

1. From the Item Refs click on to open the Item Refs browser pop up.
2. From the popup screen click on Function.



3. Click on fnNew_button.png and select fnIsNull.



4. The system will suggest the required parameters needed for this function.



5. Click on i:Value1 and select contractdescription.



6. Click on i:True and then click on Value. Enter text value and click ok



7. Click on i:False, select contractdescription and click ok.



8. Click on to confirm the selection.
9. Once apply button is clicked. The Item Ref will be as per below.

More information about API functions can be found in API Functions.

Example of Sort Item Refs

For Example, using Contract object, sort by contractseqnum.

The data result returned from the API will be sorted by contractseqnum as shown below.

Example of Summary Item Refs

For Example, using Valuation object, summarized profitandlossvaluetodate and valuecurrencycode.

The data result returned from the API will display a summary value as shown below.

Example of Grouping Filter

For Example, using Valuation object, returning Strategy book, Strategy Name and Sum of totalchangevalue.

When a filter criteria involves a grouping function, such as fnSum(i:totalchangevalue) > 0. The filter citeria will have to have "Grouping Filter" checked.

The API will return data with fnSum(i:totalchangevalue) > 0 as shown below.

If "Grouping Filter" is not checked, the system will return an error as shown below:

Testing API Requests using Postman

Once the API Request URL is generated, the data can also be retrieved by an external system from CoreTRM API.

One of the ways to simulate an external system retrieving data from CoreTRM API is to use the Postman application.

Below are the steps to simulate retrieving data from CoreTRM API using Postman:

1. In order to retrieve data from CoreTRM API you have to obtain an API token first.
2. The API token can be obtained by following the steps here.
3. Once you have obtained the API token you have to include the token in the header of your API Call in Postman.
4. In Postman open a new tab and navigate to the Headers tab.
5. From the Headers tab add a new Key: Authorization and Value: Bearer XXXXX. XXX is the token that you have obtained in step 2.



*The API token will typically expire in 18 to 24 hours depending on the Tenant Settings.*

6. Next we will need the API endpoint for your environment. The API endpoint of your environment can be found in your API updates "Execute Update" view.

The endpoint will be typically be similar to https://XXXX.coretrm-app.com/api/tenantid/dataobjectdata/core_contract?itemrefs=contractdate,contractreference,contract.core_counterparty.counterpartyname,commoditieslist,contractdescription,contractapprovalstatus.dm_dataobject_item_lookup.itemdescription,otherpartytype&filter=contractapprovalstatus.dm_dataobject_item_lookup.itemdescription.eq.Proposed.and.otherpartytype.eq.T&perpage=12



7. After obtaining the API endpoint this can be entered in the URL section in Postman.
8. The action will stay as "GET" since we are retrieving data from the API endpoint.



9. Finally when you click on the "Send" button in Postman, this will retrieve the data from CoreTRM as shown below.

Back to top