iWay Trading Partner Manager Runtime Functions

Installation

Before continuing, validate the iSM installation. Runtime functions are installed during the TPM installation (when the iwxtpm.jar file is copied to the etc\manager\extensions directory).

To check if runtime functions are installed properly navigate to the iSM command prompt and type funcs. A list of all the runtime functions, along with iSM runtime functions, is displayed.

TPM runtime functions include _TPA, _TPAW, _TPID, _TPN, _TPP, _TPR, _TPS, and _TPT, which should be present in the list. The following sections provide details for each TPM runtime function.

Note: TPM runtime functions are overloaded, which means that the same function parameter can take ++ or a value. As a result, use caution when executing these functions.

TPA Function

The TPA function can be used to retrieve data for a domain from the TPM repository. To better understand the TPA function, an understanding of TPM schema and the relationship between various TPM domains like partner, system, partnersystem, messagetype, and messageformat, is required. Domains are mapped directly to the database table.

Partner and system are related through partnersystem.
Partner and message are related through partner <--> partnersystem <--> partnersystemmessages <--> messsagetype.
Businessroute and partner are related through Businessroute <--> businesschannel <--> partner. Since Businesschannel can be incoming and outgoing so businessroute has two columns idBusinessChannelFrom and idBusinessChannelTo to map the incoming and outgoing data.

Top of page

TPA Function Examples

Note that table references in this example can be both in upper or lower case, if the database in use is not case sensitive. If the value into the function call is a string with spaces or special characters, it has to be enclosed into single quotes. The last value for the function calls indicated as default, represents a value which should be returned in case there is no data available. This section provides some examples for using the TPA function. It is highly recommended to test any TPM function call using the testfuncs tool.

The following statement is the general syntax.

_TPA(DomainID, Domain, DomainProperty, 'Default value')

where:

DomainID: Is the ID field for the domain.
Domain: Is the Table reference to follow for the field retrieval.
DomainProperty: Is the column name (or field) from which the value should be retrieved.
Default value: Is the default value being returned if no data is found.

Consider the following use cases.

To find the partner name based on the known Partner ID (idPartner=2), users can create the following function:
```
_TPA(2,Partner,'name','default')
```
In the above expression, you are provided the number 2 as the Partner ID, searching in the Partner table, and retrieving the value for name, which will return the name for the partner.
To find the partner system based on the known PartnerID (idPartner=2), users can create the following function:
```
_TPA(2,/Partner/PartnerSystem/System,'name','default')
```
In the above expression, you are provided the number 2 as the Partner ID, creating a relationship between Partner and System objects through PartnerSystem, and retrieving the name for the system.
For example, the following image shows how to retrieve the CanadaSystem value, which can be seen in the System column for the Sunkis Canada partner, which has a PartnerId of 2.
To find the contact name based on the known PartnerID (idPartner=2), users can create the following function:
```
_TPA(2,/Partner/Contact,'contactname','default')
```
In the above expression, you are provided the number 2 as the Partner ID, searching the Contact table associated with the partner, and retrieving the contactname value which will return the name of the contact for the partner.
For example, the following image shows how to retrieve the contact name, Elisavet Shirshnev, from the Partner Contact list.
To find the metadata value (for example, ack) based on the known PartnerID (idPartner=2), users can create the following function:
```
_TPA(2,Partner,'ack','default')
```
In the above expression, you are provided the number 2 as the Partner ID, and finding extended metadata attribute ack.
For example, the following image shows how to retrieve C:\Training\TPM\safestore\Canada\ack from the extended metadata of the partner, stored in the ack node.
To find the partner system based on the known Business Route ID (idBusinessRoute=7), users can create the following function:
```
_TPA(7,/BusinessRoute/BusinessChannelFrom/PartnerSystem,'name','default')
```
For the outbound context, you must indicate BusinessChannelTo.
In the above expression, you are provided the number 7 as the Business Route ID, and looking for a corresponding PartnerSystem which is related by BusinessChannelFrom (indicating incoming context).
For example, the following image shows how to retrieve the partner system Sun_Can_SAP associated with Invoice - Sun_Can_SAP from the Channel From field.
To find the message format name based on the known Business Route ID (idBusinessRoute=7), users can create the following function.
```
_TPA(7,/BusinessRoute/BusinessChannelFrom/PartnerSystemMessages/MessageType/MessageFormat,'name','default')
```
In the above expression, you are provided the number 7 as the Business Route ID, and looking to retrieve the Message Format From field associated with the given route. As such, in the above reference, you are searching in the BusinessRoute, finding the BusinessChannelFrom for a given Business Route ID, then retrieving corresponding PartnerSystemMessages value and getting MessageType (for example, Invoice), and then based on the MessageType, you are searching in the MessageFormat domain and finding its name, which is AXAPTA30.
For example, the following image shows how to retrieve AXAPTA30 from the Message Format From field.
To find the metadata value based on the known Business Route ID (idBusinessRoute=7), users can create the following function.
```
_TPA(7,BusinessRoute,'primary','default')
```
In the above expression, you are provided the number 7 as the Business Route ID, and retrieving a value for the metadata node primary.
For example, the following image shows how to retrieve YES from the primary metadata node.
TPM functions have the ability to take SQL conditions and custom function arguments directly in runtime. These SQL statements are appended directly to the SQL statement prepared for the runtime function. For example:
```
_TPA('and Description=\'Invoices\'',BusinessRoute,'Name','not found')
```
In the above expression, you are provided the BusinessRoute description of Invoices rather than a Business Route ID. As a result, a Business Route Name which has this description will be returned. Internally, the following SQL statement will be formed and executed:
```
select Name from BusinessRoute where 1=1 and Description='Invoices'
```
Note that the apostrophe character (') needs to be escaped as that is a special character in the runtime functions. For more information on iWay Functional Language (iFL) syntax, see the iWay Functional Language Reference Guide.
In the event that the values for the TPA function call are retrieved using an SREG (Special Register), then the _CONCAT() function can be used to create the where clause string as shown in the modified example below.
```
_TPA(_CONCAT('and Description=',SREG(RouteDescription)),BusinessRoute,'Name','not found')
```
where:
SREG(RouteDescription)
Evaluates to ‘Invoices’.
One of the complex examples of combining multiple functions together is to retrieve metadata values associated with Partner System Message. Given only the Partner Name and Message Name, the application can find a proper metadata field, for example, a Transform which should be applied to the message when it is received on a given Partner System.
The following statement enables the application to process any message type coming from any partner and still apply the proper transformation before sending the message to the outbound processing.
```
_tpa(_CONCAT("partner.idpartner='",SREG(partnerid),"' ;
Messagetype.Name = 
'",SREG(MessageType),"'"),"/messagetype/businesschannelfrom/partnersystem/
partner/partnersystemmessages/BUSINESSCHANNEL","transform",'notfound')
```
Note:
- The SREG(partnerid) is already available and will evaluate to the Partner ID for the message being received. This can be done as an initial message processing where the TPID() function can be used to retrieve the Partner ID based on the incoming document.
- SREG(MessageType) is already available and will evaluate to the Message Type being processed. This can be done by retrieving or identifying the message type based on the incoming document.
To put into perspective, the following image shows what is being extracted.
You are given the partner Sunkis USA, which has the Partner System Sunkis_USA. The processing inbound customized message, MSG1, has an associated metadata node transform with the value MSG_1_USA, indicating that before processing this message, this canonical transform should be applied.
After SREG(MessageType) is evaluated to MSG1, and SREG(partnerid) is evaluated to 3, you have the following function call:
```
_tpa(_CONCAT("partner.idpartner='",3,"' ; Messagetype.Name = 
'",MSG1,"'"),"/messagetype/businesschannelfrom/partnersystem/partner/
partnersystemmessages/BUSINESSCHANNEL","transform",'notfound')
```
Internally, this TPA statement will result in selecting the transform metadata value where Partner ID is 3 and Message Name is MSG1. The selection will be done from the BUSINESSCHANNEL table, which is the last table in the table list. The relationship between all of the tables will be formed based on primary and foreign key relationships.

TPAW Function

The TPAW function is used to check a domain code and update it with the passed value if it is found. This function can also be used to increment or decrement the values, which is useful when creating a new control number. The TPAW function works the same as the TPA function with the exception that if a domain code is found, then it is incremented. If the data is not incremented, then the string “TPAW, Data not updated” is returned. Otherwise, the updated value is returned.

domainId
domain
domainCode
Operator (++ and -- or new Domain Value)

For example:

_TPAW(1,'system','controlnumber','++')

This example will increment the controlnumber by 1 in case it is found and will return the incremented value. In the event that the incremented value is not a number, then it will throw an exception and will return the exception.

Note: Use caution while passing the values. Passing the wrong values could make the system unstable.

For example:

Executing _TPAW(1,'system','controlnumber','value1') will update the controlnumber to value1 if systemid = 1 is found.
Executing _TPAW(1,'system','controlnumber','11') will update the controlnumber to value 11 is systemid = 1 is found.

The TPAW function has the following signature:

_TPAW(domainId, domain, domainCode, Operator)

TPID Function

The TPID function returns the unique ID for the table based on a column name and the value that is passed. The return value can then be used in conjunction with other runtime functions. This function accepts four parameters and returns a unique table ID:

Domain
DomainProperty
DomainValue
WhereClause

For example:

To retrieve the Partner ID, based on a known Partner Name, users can use the following function:
```
_TPID(Partner,'Name','Sunkis USA')
```
The Partner ID for the Partner with the name Sunkis USA, is returned.
To retrieve the Partner ID, based on a known Partner metadata value, users can use the following function:
```
_TPID(Partner,'ReceiverID','2002452')
```
The Partner ID for the partner with the metadata field ReceiverID, equivalent to 2002452, is returned.

The TPID function call can also be used in conjunction with other calls that follow the standard of iWay Functional Language.

For example, to retrieve the ChannelTarget for the system, where the System Name is Canada System, users can use the following function:

TPA(_TPID(System,'Name','CanadaSystem'),System,ChannelTarget,'default')

The following list shows the results:

_TPID(System,'Name','CanadaSystem') evaluates to 3 as the System ID.
_TPA(3,System,ChannelTarget,'default') evaluates to TPM.Sunkis.Canada, as shown in the following image.

TPN Function

The TPN runtime function returns a trading partner name that is defined in a particular domain. This function accepts two parameters:

domain (for example, DUNS or SAP)
domainvalue (for example, DUNS ID or SAP Value)

For example executing _TPN('403815327','DUNS') will return a trading partner name where domain code = 'DUNS' and Domain ID = '403815327'. Running this function will execute the following underlying SQL:

SELECT DISTINCT Partner.Name FROM Partner, BusinessChannel, BusinessRoute, PartnerCodeSub WHERE Partner.idPartner = BusinessChannel.partner_idpartner

AND ((BusinessChannel.idBusinessChannel = BusinessRoute.idBusinessChannelFrom AND PartnerCodeSub.FromDomain = 'DUNS'

AND PartnerCodeSub.FromCode = 403815327) OR ((BusinessChannel.idBusinessChannel = BusinessRoute.idBusinessChannelTo

AND PartnerCodeSub.ToDomain = 'DUNS' AND PartnerCodeSub.ToCode = 403815327)))

AND BusinessRoute.idBusinessRoute = PartnerCodeSub.BusinessRoute_idTradeRoute

Note that the TPN value is acquired from the incoming businesschannel as well as the outgoing businesschannel.

The usage for the TPN function is:

_TPN(Domain, Domain Value)

TPP Function

The TPP function is used to access any attribute (column) from a partner table (domain). It accepts four parameters:

PartnerName
AttributeName
Default value for no data
Default Value

The fourth value is currently the default value that is returned. However, it is reserved for future use.

For example:

_TPP('walmart','buname','Default','No Data Found')

This example returns the attribute buname from a partner where partnername is walmart. In case ‘walmart’ is found but buname attribute is empty, 'Default' is returned. In the event that 'walmart' is not found, then the TPP function will return the “NO_DATA_FOUND” string.

The TPP function has the following signature:

_TPP(PartnerName, AttributeName, Default Value for no data, Default Value)

TPR Function

The TPR function returns trading partner routes for a given message type and is useful in determining where to send the messages based on the message type, domain, or code. The TPR function accepts five parameters:

messagetype
fromDomain
fromCode
toDomain
toCode

Apart from the messagetype parameter, passing empty values to the TPR function will cause this function to ignore that value and create a result set based on the values that are passed. The messagetype parameter becomes the mandatory parameter and the remaining parameters are all optional. The TPR function can return multiple values and data is returned in XML format.

For example:

Executing _TPR('ProductCatalogUpdate',,'5790000243433', , '5790001669133') returns:

<TPR><FROM><DOMAIN></DOMAIN><CODE>5790000243433</CODE></FROM><TO><DOMA IN></DOMAIN><CODE>5790001669133</CODE><MESSAGETYPE>ProductCatalogUpdat e</MESSAGETYPE><ROUTEID>2103</ROUTEID><SYSTEMID>1472</SYSTEMID></TO></ TPR>

Executing _TPR('DemandForecast','ZVMI','DCR_010', 'ZVMI', '02200650')returns:

<TPR>
<FROM><DOMAIN>ZVMI</DOMAIN><CODE>DCR_010</CODE></FROM><TO><DOMAIN>ZVMI </DOMAIN><CODE>02200650</CODE><MESSAGETYPE>DemandForecast</MESSAGETYPE ><ROUTEID>208</ROUTEID><SYSTEMID>24</SYSTEMID></TO><TO><DOMAIN>ZVMI</D OMAIN><CODE>02200650</CODE><MESSAGETYPE>DemandForecast</MESSAGETYPE><R OUTEID>210</ROUTEID><SYSTEMID>87</SYSTEMID></TO></TPR>

Executing _TPR('Invoice',,'5790000243433',, '5790001669133') returns:

<TPR><FROM><DOMAIN></DOMAIN><CODE>5790000243433</CODE></FROM><TO><DOMA
IN></DOMAIN><CODE>5790001669133</CODE><MESSAGETYPE>Invoice</MESSAGETYP
E><ROUTEID>2100</ROUTEID><SYSTEMID>1472</SYSTEMID></TO></ TPR>

It is expected that the process flow calling the TPR function will take the output XML and iterate over it to get the correct ROUTEID and send the messages accordingly to these ROUTEID instances.

The TPR function has the following signature:

_TPR(messagetype, fromDomain, fromCode, toDomain ,toCode)

TPS Function

The TPS function returns substitution codes for the given BusinessRoute and PartnerCodeSub. Code substitutions in TPM are related to translations at the partnersytem level.

The TPS function accepts six parameters. The first parameter (SubstitionValueName) should be one of the following values to determine which substitution value to return:

SUBSTFROMCODE: Pass this in case substitution from code is needed.
SUBSTFROMDOMAIN: Pass this in case substitution from domain is needed.
SUBSTTOCODE: Pass this in case substitution to code is needed.
SUBSTTODOMAIN: Pass this in case substitution to domain is needed.

The remaining parameters are:

RouteID
FromDomain
FromCode
ToDomain
ToCode

For example:

_TPS('SUBSTFROMCODE',1,'DUNS',403815327,'Buyer',0000100075) returns the substituted From Code where routeid = 1 and fromdomain = 'DUNS' and fromcode = '403815327' and toDomain = 'Buyer' and toCode = '0000100075'

Substitution is done based on the lookup performed in the PartnerCodeSub table.

In the event that no substitution is found, then the “NO_DATA_FOUND” string is returned.

The TPS function has the following signature:

_TPS(SubstitionValueName, RouteID, FromDomain, FromCode, ToDomain, ToCode)

TPT Function

The TPT runtime function provides a mechanism for retrieving code substitution values from one message format to another. This should not be confused with Partner Code substitutions that are obtained using the TPS function. TPT code substitutions are purely for message level translations (for example, the MeasurementValue field for Partner A is KG while Partner B expects LBS).

The TPT function accepts four parameters:

formatname
formatfrom
formatto
code

The TPT function has the following signature:

_TPT(formatname,formatfrom,formatto,code)

If a substitution is found the function returns the substituted value, else it returns the passed value.

The following SQL statement is run within the application function logic:

select SubstCode from codesubstitution where name=#formatname# and
StandardFrom=(select idStandard from standard where Name = #formatFrom# )
and StandardTo=(select idStandard from standard where Name = #formatTo#
) and Code=#code#

In addition, the application function logic checks if substcode is null or not. If substcode is null, then #code# is returned.

Debugging Runtime Functions

Debugging TPM runtime functions can be difficult if you are debugging directly from the process flow or other iSM components. As a best practice, it is recommended to first use TPM runtime functions directly from the iSM command prompt. This requires access to the iSM command prompt. If iSM is running on a remote machine, then remote access to that machine is also required.

Top of page

Procedure: How to Debug Runtime Functions

To debug runtime functions:

If iSM is running as a service, stop the service.
Open a new terminal window (for example, a DOS prompt) and navigate to the iwayhome directory.
The iwayhome directory must contain iway7.cmd or ./iway7.sh, depending on which platform you are using.
Start iSM in the terminal window using iway7.cmd or ./iway7.sh.
Once started, the terminal window displays the following prompt:

Note: If the Enter command:> prompt does not display, press Enter after iSM is started.
Type funcs to check if all the TPM runtime functions are installed properly, as shown in the following image.
Type SET DEEP on at the command prompt to enable the DEEP debug level and to view the complete runtime information.
Note: XML files are required to execute runtime functions.

Create a simple XML file using the following format:

<?xml version="1.0" encoding="UTF-8"?><noop/>
located at C:\test.xml

Type the following command to start the test tool:
```
tool testfuncs C:\test.xml 
```
The funcs - > prompt displays, which allows you to execute TPM runtime functions.
Enter the TPM runtime function you want to check and press Enter.
For example:
```
_tpid("PARTNER","ftpport","90","geq”)
```
This will produce output with the last line reading <tpids><tpid>1</tpid><tpid>2</tpid><tpid>3</tpid></tpids>, as shown in the following image.
Note: The SQL statement is executed with the TPM runtime function along with the other debug statements.