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.

To access the API Builder for generating formatted JSON updates, go to System Admin and then to the API Builder->API Updates tab.

Example of using method Update If Match else Insert

Testing API Updates using Postman

API Updates

To start building a formatted JSON sample from API Updates view:

1. Click on to create a new line.

2. In API Update Name enter the name for the API update.

3. Click to confirm creation.

4. To edit API update details after creation Click to edit.

To start building a formatted JSON sample from the Objects panel:

1. Click on to create a new line.

2. In Order indicate the order number of the Object update.

3. In Method select the applicable method. Below are the available methods:

Delete this is used to delete an existing data record when calling the API. The primary key of the object is used to find the matching record to be deleted. The primary key of the object has to be included as one of the Item Refs as part of the JSON.

Insert this is used to insert a new data record when calling the API.

Update this is used to update an existing data record when calling the API. The primary key of the object is used to find the matching record to be updated. The primary key of the object has to be included as one of the Item Refs as part of the JSON.

Update if Match, this is used to update an existing record when calling the API. The key(s) used to find the matching data record to be updated is set in "Match Item Refs". If no matching records are found, the system will not update any record.

Update if Match else Insert this is used to update an existing record when calling the API. They key(s) used to find the matching data record to be updated is set in "Match Item Refs". If no matching records are found, the system will insert a new data record.

4. In Object select the object you wish to perform an action on.

5. In Item Refs select the Item refs that you wish to perform an action on.

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

6. In Match Item Refs select the Match Item Refs to be used to identify a data record to be updated.

*Examples of using Match Item Refs can be found here.*

7. Click to confirm creation.

8. To edit Object details after creation Click to edit.

*Multiple methods / objects can be applied in the same update. If any should fail all updates are rolled back.*

Once the API updates are setup, we can also populate some sample data in the row view.

1. Click on to create a new line.

2. In Order indicate the order number of the Object.

3. In Item Values enter the values for each Item Ref.

*Each Item ref. value can be delimited with commas. Eg A TestLocation, A TestDescription, PORT.*

4. Click to confirm creation.

5. To edit row details after creation Click to edit.

Once row data is added the system will provide a sample JSON which can be used to update the system as below.

A test of sending the above JSON data can also be executed within the API builder.

From the Execute Update view you can click on the button to post the data to the API.

After the API Post the system will return a response message in JSON format indicating success or failure as below.

Item Refs

To start selecting Item Refs to be included in the API updates:

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 update. 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 locationname Item Ref from the Location object.

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

For Example below is selecting locantiondescription item refs from location object.

4. 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.

Example of using method Update If Match else Insert

For example, we can update the Price Series Price object by using a set of Match Item Refs and if there is no matching data during update, the system will create a new price data row.

Method: Update if Match else Insert

Object: Price Series Price

Item Refs: core_priceseries_pricetype.dataproviderid2,pricedatetime,forward.core_price_period.periodid,core_priceseries_pricetype.pricetypecode,priceamount

Match Item Refs: core_priceseries_pricetype.dataproviderid2,pricedatetime,forward.core_price_period.periodid,core_priceseries_pricetype.pricetypecode

An Example of the data that can be post to the API. Row 100 is an example of Futures Price update. Row 200 is an example of Spot Price update.

The Sample formatted JSON from the above example.

The above example is using dataproviderid2, price datetime, period id(Use by Forward and Futures Price Series) and priceseries pricetype code as a unique key to determine if there is already an existing data row containing this combination of data. If a match is found, the system will update the price amount, else the system will insert a new data row.

Testing API Updates using Postman

Once the formatted JSON is created this can be used as a schema for the external system to post data to CoreTRM API.

One of the way to simulate an external system posting data to CoreTRM API is to use Postman application.

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

1. In order to post data to CoreTRM API you have to obtain an API token first.

2. 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 typically expired in 18 to 24 hours depending on 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 like https://XXX.coretrm-app.com/api/tenantid/dataobjectdata

7. After obtaining the API endpoint, this can be inputted in the URL section in the Postman.

8. Next change the action to "POST" for posting data to API endpoint.

9. Next go to the tab "Body", select "raw" and change the format to JSON.

10. Next in the body copy and paste the formatted JSON provided in API Request into the body area.

11. Finally when you click on the "Send" button in Postman, this will post the data to CoreTRM.