Interface Builder

CoreTRM Interface Builder allows you to create custom incoming and outgoing interface message schema and endpoints which can be used to interface with external system. For Outgoing Interfaces, it allows you to create message schema in XML,JSON and CSV format which can be used to send to an external endpoint. It support sending via HTTP, FTP and Storage Account. For Incoming Interfaces, it allows you to create an interface endpoint in the system to receive custom data from another system. It currently support XML format only. For Reterival Interfaces, it allows you to create interface to retreival data from a storage location. It currently support retrieval from Storage Account and in XML format only. Currently, CoreTRM can deliver or receive messages in XML, JSON, HTML and Email Format. The delivery method available are HTTP, FTP, Storage Account and Email.

To access Interface Builder go to System Admin and then to the Interface Builder tab.

Creating Outgoing Interfaces

Creating Incoming Interfaces

Creating Retrieval Interfaces

Creating Outgoing Interfaces

CoreTRM allows you to create custom message template in XML, JSON and CSV Format. We will use an example to show how to setup an outgoing interface.

In our example, we will send create a XML outgoing message with some data from Contract Item Object.

To create a new Outgoing Interface, in Outgoing Interface view:

1. Click on to create a new line.
2. In Interface Id, enter a unique interface id. In our example, we are using "Outgoing Interface Example".
3. In Object Name, select an object from which the interface will retrieve data from. In our example, we are using "Contract Items".
4. In By Call?, tick this box if this interface is triggered by call like a button. Using by call will required additional setup from CoreTRM. Please contact support.
5. In By Schedule?, tick this box if this interface is triggered by schedule. Using by schedule will required additional setup from CoreTRM. Please contact support.
6. In Delivery Type, select the applicable delivery type to be used for this interface. The Delivery Type available are HTTP, Storage Account and FTP. In our example, we are using "HTTP".
7. In Delivery Format, select the applicable delivery format to be used for this interface. The Delivery Format available are JSON, XML and CSV. In our example, we are using "XML"
8. In Delivery Address, enter the destination endpoint address. In our example, we are using "localhost".
9. In Do not Deliver?, tick this box if you are going to test the message output and do not want the message to be send to the delivery address.
10. In Active?, tick this box to make this interface active.
11. In Payload Item Refs, select the applicable Payload Items. The items selected will appear in the output file. This is used for JSON and CSV format currently only.
12. In Filename Item Refs, this is use to setup the filename of the export file. This works for Storage Account only.
13. In Credentials, select a credential to use if the destination address requires authentication. The authentication type that are supported are basic authentication and Storage Account Credentials .

*Credentials are setup in System Admin-> Interface Builder-> Interface Credentials.*

14. In Test Parameters, enter any criteria for testing the interface. In our example, we are using contractseqnum as a testing criteria so that we can test message generated for specific contract.
15. In Start Tag, enter any start tag to be generated as part of the message. This may be used as XML or HTML start tag.
16. In End Tag, enter any end tag to be generated as part of the message. This may be used as XML or HTML end tag.
17. In Email Subject, enter any applicable email subject. This is used specifically for delivery format "Email".
18. In Webhook Num, display the unique webhook num generated for this interface after the interface details are created.
19. Then, click on to confirm the creation.
20. To edit outgoing interface details after creation, Click to edit.

After the interface data are setup above, next we will need setup the schema of the message.

Schema allow you to define the delivery format schema with specific tags required by the destination endpoint. Schema is currently is used for XML format only. To create schema items, we will have to first create a scheme group. Schema Group allow you to group items in groups for easy organisation.

Outgoing Interface Schema (Top)

To create a new Outgoing Interface, in Schema tab and Schema Groups:

1. Click on to create a new line.
2. In Order Num, enter an order number for this line. In our example, we are using "100".
3. In Group Type, select an applicable group type. For outgoing interface, it will be "Send". For incoming interface, it will be "Responds".In our example, we are using "Send".
4. In Start Tag, enter any start tag for this group schema. Typically, this is used for HTML delivery format. In our example, this is blank.
5. In End Tag, . enter any end tag for this group schema. Typically, this is used for HTML delivery format. In our example, this is blank.
6. In Repeating Group?, tick this box if the data should be repeated if there are more than 1 row of data. Typically, for contract items we will use Repeating group since one contract can have more than one contract item. In our example, we are will tick the box.
7. In Active?, tick this box to set this schema group active.
8. Then, click on to confirm the creation.
9. To edit schema details after creation, Click to edit.

After each Schema group, we can create the individual JSON elements to be generated by the system.

Outgoing Interface Schema Group Items (Top)

To create a new Outgoing Interface, in Schema tab and Groups Items:

1. Click on to create a new line.
2. In Order Num, enter an order number for this line. In our example, we are using "100".
3. In Start Tag, enter a start tag for this item. Typically, it is the element start attribute. For our example, we are using "SpotTerm" to indicate the value to be sent to destination that this value is spot or term.
4. In Item Ref., select the item ref to set the data to be sent. In our example, we are using " spottermtype.dm_dataobject_item_lookup.itemdescription" to send out Spot or Term value.
5. In End Tag, enter a end tag for this item. Typically, it is the element start attribute. For our example, we are using "/SpotTerm" to indicate the value to be sent to destination that this value is spot or term.
6. In Method, Object, Match Item Refs, Match Item REf Values, Translate Object, From Item Id, To Item Id, Set to Null if value Equals, Response Success Value, Response Error Values, Response Message?, this are used by incoming interface message only.
7. In Active?, tick this box to set this group items active.
8. In Comments, enter any applicable comments for this group items.
9. Then, click on to confirm the creation.
10. To edit group items after creation, Click to edit.
11. Below is an example of the group items that can be included in this outgoing interface message.

After we have setup the group items, we can test the XML output message.

Outgoing Interface Test Output Message (Top)

To test the delivery output message:

1. Select the Interface Message id that you wish to test the sending of interface message.



2. Click on to trigger the interface.

*Be sure to have set a testing parameters before testing. In our example, we are testing one contract using "core_contract.contractreference.eq.A00222".*

3. After the interface is triggered successfully, we can check the results in "Deliveries" Tab like below:

The test results will contain the payload that will be sent as a message to the destination endpoint.

Creating Incoming Interfaces

CoreTRM is able to receive interface message from external system. We will use an example to show how to setup an incoming interface.

In our example, we will receive an XML message from an external system. The XML will update the container details if a matching IMONO exist else it will create a new container.

To create a new Incoming Interface, in Incoming Interface view:

1. Click on to create a new line.
2. In Interface Id, enter a unique interface id. In our example, we are using "Incoming_Interface_Example".
3. In Object Name, select an object from which the interface will update the data to. In our example, we are using "Container".
4. In Request Type, select the applicable request type to be used for this interface. The Request Type available are HTTP and FTP. In our example, we are using "HTTP".
5. In Request Format, select the applicable request format to be used for this interface. The Request Format available are JSON, XML and HTML. In our example, we are using "XML"
6. In Request Address, enter endpoint address which will be provided to the external system. The endpoint will follow the address created here. You will need to start the address with the word "interface?interfaceid=interfaceidname". In our example, it will be "interface?interfaceid=Incoming_Interface_Example".

The full address is https://xxx.coretrm-app.com/interface?interfaceid=Incoming_Interface_Example

7. In Strict Schema?, tick this box to enforce strict schema validation for incoming messages. The incoming message schema has to be exactly the as the schema setup. Missing 1 xml tag will fail the validation.
8. In Active?, tick this box to make this interface active.
9. In Payload Item Refs, select the applicable Payload Items. This is used for Email delivery method.
10. In Credentials, select a credential to use if the destination address requires authentication. The authentication type use here is basic authentication.

*Credentials are setup in System Admin-> Interface Builder-> Interface Credentials.*

11. In IP Address List, select the list of IP addresses that are allowed to send to this endpoint.

*IP Addresses are setup in System Admin-> Interface Builder-> IP Addresses.*

12. In Test Parameters, enter any criteria for testing the interface. This is only for outgoing interface.
13. In Test Responds Body, this is use to simulate incoming message without needing an external system. For Example, paste the actual message here and click on the test interface button. This will process the message like incoming messages.
14. In Start Tag, enter any start tag to be generated as part of the message. In our example, we can include the xml message start encoding tag " ".
15. In End Tag, enter any end tag to be generated as part of the message. This may be used as HTML end tag..
16. In Webhook Num, display the unique webhook num generated for this interface after the interface details are created.
17. Then, click on to confirm the creation.
18. To edit incoming interface details after creation, Click to edit.

After the interface data are setup above, next we will need setup the schema of the message.

Schema allow you to define the received format schema with specific tags provided by the s endpoint. To create schema items, we will have to first create a scheme group. Schema Group allow you to group items in groups for easy organisation. In our example, we will create a few group to match the schema from the source endpoint.

Incoming Interface Schema (Top)

To create a new Incoming Interface, in Schema tab and Schema Groups:

1. Click on to create a new line.
2. In Order Num, enter an order number for this line.
3. In Group Type, select an applicable group type. For incoming interface, it will be "Receive" and "Response". "Received" is used to capture the details data and "Response" is used to send out an responds based on the action in the system.
4. In Start Tag, enter any start tag for this group schema. In our example, we can specify the start tag used for the details data and return reponds.
5. In End Tag, . enter any end tag for this group schema. In our example, we can specify the end tag used for the details data and return reponds..
6. In Repeating Group?, tick this box if the data should be repeated if there are more than 1 row of data.
7. In Active?, tick this box to set this schema group active.
8. Then, click on to confirm the creation.
9. To edit schema details after creation, Click to edit.

After a Schema group is created, we can create the individual XML elements that is part of the Schema Group. In our example, the group item below is used for importing container into the system.

Incoming Interface Schema Group Items (Top)

To create a new Incoming Interface, in Schema tab and Groups Items:

We will use Order Num 2 as an exmaple.

1. Click on to create a new line.
2. In Order Num, enter an order number for this line. In our example, we are using "200".
3. In Start Tag, enter a start tag for this item. Typically, it is the element start attribute. For our example, we are using "VSLNAME" to indicate the value to receiving from the source is Vessel Name.
4. In Item Ref., select the item ref to set the data to be recevied. In our example, we are using " containername" to match back the Vessel Name.
5. In End Tag, enter a end tag for this item. Typically, it is the element start attribute. For our example, we are using "/VSLNAME" to indicate the value to be sent from the source that is Vessel Name.
6. In Date Format, set the date format of the receiving item value to YYYYMMDD.
7. In Method, select the applicable method to use. In our example, "Update If Match else insert" will be used since we will insert the containername and details if there is no IMONO match.

"Update if Match" is used when if there is a matching item, the system will update else no action.

"Update" is used when if there is a matching item.

8. In Object, select the applicable object. Related to the method selected, which object will be used to find the match. In our example, we will use "Container".
9. In Match Item Refs, select the applicable Item Refs. Related to the object selected, which item ref will be used. In our example, we will use "imonumber".
10. In Match Item Ref Values, select the applicable Item Refs Values. Related to the Item Ref selected, which item ref value will be used to find the match. In our example, we will use "imonumber".
11. In Translate Object, select the applicable object to use if translation is required. Translation refers to instead of using an item ref value, it can use another value to update. In our example in order num 500, for containertype, we will object "Container".
12. In From Item Id, select the applicable from Item Id to use if translation is required. In our example in order num 500, for containertype, we will use "imonumber".
13. In To Item Id, select the applicable to Item Id to use if translation is required. In our example in order num 500, for containertype, we will use "fnStaticText(V). With this, the system will actually insert V instead of imonumber value to containertype.
14. In Active?, tick this box to set this group items active.
15. In Comments, enter any applicable comments for this group items.
16. In Value Required?, tick this box if for this item, a value is required before processing the incoming message.
17. Then, click on to confirm the creation.
18. To edit group items after creation, Click to edit.

Creating Retrieval Interfaces

CoreTRM also allows the creation of interfaces that retrieve data from a location. The location can be from a Storage Account or FTP.

Currently, we only support retrieval of XML from a Storage Account.

To create a new Retrieval Interface, in Retrieval Interface view:

1. Click on to create a new line.
2. In Interface Id, enter a unique interface id. In our example, we are using "Price Retrieval".
3. In Object Name, select an object from which the interface will update the data to. In our example, we are using "Price Series Price".
4. In Retrieval Type, select the applicable retreival type to be used for this interface. The Retrieval Type will be "Storage Account". Storage Account is the only type supported currently.
5. In Retreival Format, select the applicable retreival format to be used for this interface. The Retreival Format available is XML only currently. In our example, we are using "XML"
6. In Retreival Address, enter the storage account container path. In our example, it will be "interfaces/alex-test".
7. In Active?, tick this box to make this interface active.
8. In Payload Item Refs, this is not applicable for Reterival interface.
9. In Credentials, select a credential to use if the storage account requires authentication. For Storage account, Account Name and Account Key is required.

*Credentials are setup in System Admin-> Interface Builder-> Interface Credentials.*

10. In IP Address List, select the list of IP addresses that are allowed to send to this endpoint.

*IP Addresses are setup in System Admin-> Interface Builder-> IP Addresses.*

11. In Test Parameters, this is not applicable for Reterival interface.
12. In Start Tag, enter any start tag if required. In our example, we can include the xml message start encoding tag " ".
13. In End Tag, enter any end tag as part of the message. This may be used as HTML end tag..
14. In Webhook Num, display the unique webhook num generated for this interface after the interface details are created.
15. Then, click on to confirm the creation.
16. To edit retreival interface details after creation, Click to edit.

After the interface data are setup above, next we will need setup the schema of the message.

Schema allow you to define the received format schema with specific tags provided by the destination endpoint. To create schema items, we will have to first create a scheme group. Schema Group allow you to group items in groups for easy organisation. In our example, we will create a few group to match the schema from the source XML File.

Incoming Retrieval Schema (Top)

To create a new Reterival Interface, in Schema tab and Schema Groups:

1. Click on to create a new line.
2. In Order Num, enter an order number for this line.
3. In Group Type, select an applicable group type. For retrieval interface, it will be "Receive" and "Response". "Received" is used to capture the details data and "Response" is used to send out an responds based on the action in the system.
4. In Start Tag, enter any start tag for this group schema. In our example, we can specify the start tag used for the details data and return reponds.
5. In End Tag, . enter any end tag for this group schema. In our example, we can specify the end tag used for the details data and return reponds..
6. In Repeating Group?, tick this box if the data should be repeated if there are more than 1 row of data.
7. In Active?, tick this box to set this schema group active.
8. Then, click on to confirm the creation.
9. To edit schema details after creation, Click to edit.

After each Schema group, we can create the individual XML elements that is part of the XML message. In our example, the XML element will only be in "Header" and "Data" group.The example below is referring to "Data" Schema Group.

Reterival Interface Schema Group Items (Top)

To create a new Reterival Interface, in Schema tab and Groups Items:

We will use Order Num 300 as an exmaple.

1. Click on to create a new line.
2. In Order Num, enter an order number for this line. In our example, we are using "300".
3. In Start Tag, enter a start tag for this item. Typically, it is the element start attribute. For our example, we are using "Amount" to indicate the value to receiving from the source is Price Amount.
4. In Item Ref., select the item ref to set the data to be recevied. In our example, we are using "priceamount" to match back the priceamount.
5. In End Tag, enter a end tag for this item. Typically, it is the element start attribute. For our example, we are using "/Amount" to indicate the value to be sent from the source that is Price Amount.
6. In Date Format, set the date format of the receiving item value. Not use in our example.
7. In Method, select the applicable method to use. In our example, "Update If Match else insert" will be used since we will insert the priceamount if there is no priceseriespricetypeseqnum and pricedate match.

"Update if Match" is used when if there is a matching item, the system will update else no action.

"Update" is used when if there is a matching item.

8. In Object, select the applicable object. Related to the method selected, which object will be used to find the match. In our example, we will use "Price Series Price".
9. In Match Item Refs, select the applicable Item Refs. Related to the object selected, which item ref will be used to find the match. In our example, we will use priceseriespricetypeseqnum and pricedate.
10. In Match Item Ref Values, select the applicable Item Refs Values. Related to the Item Ref selected, which item ref value will be used. In our example, we will use priceseriespricetypeseqnum and pricedate.
11. In Translate Object, select the applicable object to use if translation is required. Translation refers to instead of using an item ref value, it can use another value to update.
12. In From Item Id, select the applicable from Item Id to use if translation is required.
13. In To Item Id, select the applicable to Item Id to use if translation is required.
14. In Active?, tick this box to set this group items active.
15. In Comments, enter any applicable comments for this group items.
16. Then, click on to confirm the creation.
17. To edit group items after creation, Click to edit.

Back to top