Converters

What Is Converters?

Converters are the functions that process the value of the selected variable before it is used. They are added when the Add functions switch is turned on in the Add variable window and they are applied in the order in which they are added: the first function takes the value of the variable and the next function takes the result of the previous one. In the interface 46 functions are offered; in the function list every row appears in the form group name - function name, and the functions without a group are listed only with their names. The headings below are the same as the order in the list.

The typical use: converting a header value to lowercase and taking its hash, extracting a field from the body with JSON, narrowing an IP address to a block and comparing it with a list.

The Function Rows

When the Add functions switch is turned on, the Function 1 row is added to the window. Every new row comes ready with the JSON query function and the $.key argument; the function wanted is changed by selecting it from the list.

• With the button a new function row is added; the rows are numbered in the form Function 1, Function 2.
• With the button the row is deleted. When a single row remains, this button is not displayed.
• While there are two or more rows, the order of the functions is changed by dragging from the handle on the left of the row.
• When the function is changed in a row, the arguments of that row return to the defaults of the new function.
• When the Add functions switch is turned off and on again, the previous rows come back.
• The function list does not change according to the variable; the same 46 functions are offered in all the variables and in all the fields.
• In the AGS OTP variables the Add functions row is not displayed; a function is not added to these variables.

Reading the Tables

Column	Content
Function	The name that appears in the function list
What it does	The operation that the function makes on the value
Argument	The labels of the fields that appear when the function is selected; in parentheses the behavior of the field and its default

The Converters Group

The functions that convert the value to another representation and that decode it back. They are used when a value needs to be placed safely in a header, in a cookie or in the address line.

Function	What it does	Argument
Encode BASE64	Converts the value to the Base64 form.	-
Decode BASE64	Decodes the value written with Base64.	-
Hexadecimal	Converts the value to the hexadecimal representation.	-
URL encode	Encodes the value into the form that can be carried in the address line.	-
URL decode	Decodes the value written with the address encoding.	-
Encode URL-safe BASE64	Converts the value to the Base64 form that can be used in the address line.	-
Decode URL-safe BASE64	Decodes the value written with the Base64 suitable for the address line.	-

Math operations

Integer arithmetic. It is used together with the variables that return a number (the counters, the periods, the sizes).

Function	What it does	Argument
Integer addition	Adds the number given to the value.	Addend (an integer, 1 by default)
Integer multiplication	Multiplies the value by the number given.	Multiplicand (an integer, 1 by default)
Integer division	Divides the value by the number given.	Divider (an integer, 1 by default)
Modulo operation	Gives the remainder of the division operation.	Divider (an integer, 1 by default)

XML

Extracting a value from XML bodies and checking a path.

Function	What it does	Argument
XML query	Takes the value at the path stated from inside the XML.	XML query path (Example: root/books/[2]/title/_attr/text)
XML path type	Gives the type of the data at the XML path stated.	XML query path (Example: root/books/[2]/title/_attr/text)
XML path exists	Says whether the XML path stated is found or not.	XML query path (Example: root/books/[2]/title/_attr/text)

JSON

Extracting a value from JSON bodies and making the value usable inside JSON.

Function	What it does	Argument
JSON query	Takes the value at the path stated from inside the JSON.	JSON path (Example: $.books[0]) ($.key by default)
Convert to JSON text	Puts the value into the form that can be placed inside a JSON text.	-

FORM parameter

It appears on its own in the function list, not under a group name.

Function	What it does	Argument
FORM parameter	Takes the parameter stated from inside the form data.	Parameter name

JWT (JSON Web Token)

Reading a value from the header and payload sections of the JWT (JSON Web Token) structure. It is used to make a decision according to the user information inside the token.

Function	What it does	Argument
JWT header query	Takes the value at the path stated from the header section of the token.	JSON path (Example: $.books[0]) ($.key by default)
JWT payload query	Takes the value at the path stated from the payload section of the token.	JSON path (Example: $.books[0]) ($.key by default)

IP

Masking and location querying on an IP address.

Function	What it does	Argument
IP masking	Narrows the IP address according to the mask given; a block is obtained instead of addresses one by one.	CIDR (an integer, 24 by default; the form accepts 0-128, only the IPv4 addresses are masked)
Get country of IP	Gives the two-letter country code of the IP address (e.g. TR); for the addresses in the private and local networks the XX code, which is not in the ISO list, is returned, and if there is no match, the result stays empty.	-

Text manipulation

The length, letter case, replacement and splitting operations on the text. They are used to simplify the value before the comparison.

Function	What it does	Argument
Text length	Gives the length of the value in bytes; in the multi-byte UTF-8 characters the result is greater than the number of characters.	-
Convert to lowercase	Makes the letters lowercase.	-
Convert to UPPERCASE	Makes the letters uppercase.	-
Replace (first)	Replaces the first place that the regular expression looked for matches with the new value.	To replace (a regular expression) · New value (it can be left empty)
Replace (all)	Replaces all the places that the regular expression looked for matches with the new value.	To replace (a regular expression) · New value (it can be left empty)
Split text	Splits the value at the delimiter characters and takes the number of parts wanted starting from the part at the order stated.	Delimeter (every character is a separate delimiter; the spaces are not trimmed) · From (it starts from 1) · Total

Hash

It appears on its own in the function list, not under a group name.

Function	What it does	Argument
Hash	Takes the hash of the value; the hash is used instead of the value itself.	Hash algorithm (md5,sha256,...) (sha256 by default; 22 algorithms in the ready list)

HMAC signature

It appears on its own in the function list, not under a group name.

Function	What it does	Argument
HMAC signature	Takes the hash of the value signed with the key given.	Hash algorithm (md5,sha256,...) (sha256 by default; 22 algorithms in the ready list) · HMAC key · HMAC key format (a list: base64, hex, text; base64 by default)

Conditional text

It appears on its own in the function list, not under a group name.

Function	What it does	Argument
Conditional text	Writes the first text if the value is true and the second text if it is not.	If true · If false

FIX (Financial Information eXchange)

It reads the fields of the FIX (Financial Information eXchange) messages and checks their structure.

Function	What it does	Argument
FIX tag value	Gives the value of the tag stated in the FIX message.	FIX tag (a list, 405 unique tags; since Currency is located in the list twice, 406 rows appear; Account by default)
FIX structure check	Says whether the value is a valid FIX message or not.	-

MQTT

It reads the fields of the MQTT packets and checks their structure.

Function	What it does	Argument
MQTT value	Gives the value of the field stated in the MQTT packet.	MQTT packet type (a list: CONNECT, CONNACK; CONNECT by default) · MQTT field name (a list, it changes according to the packet type; flags by default)
MQTT structure check	Says whether the value is a valid MQTT packet or not.	-

List

It compares the value with a list written into the argument field. The In list functions give whether the value is found in the list or not, and the Mapping functions the correspondence of the row that matches. The result of the In list functions is a number: 1 if there is a match and 0 if there is not.

Function	What it does	Argument
Mapping (exact match)	Gives the correspondence of the row that matches exactly.	Mapping (a multi-line field)
Mapping (regex match)	Gives the correspondence of the row whose pattern fits; in the correspondence text the parts that match are used with back references such as \1 and \2.	Mapping (a multi-line field)
Mapping (substring match)	Gives the correspondence of the row that fits the containment rule.	Mapping (a multi-line field)
Mapping (IP/cidr match)	Gives the correspondence of the row that fits the address or block match.	Mapping (a multi-line field)
Mapping (beginning match)	Gives the correspondence of the row whose beginning matches.	Mapping (a multi-line field)
Mapping (ending match)	Gives the correspondence of the row whose ending matches.	Mapping (a multi-line field)
In list (exact match)	Says whether the value is found in the list exactly or not.	List to query (a multi-line field)
In list (regex match)	Says whether the value fits one of the patterns in the list or not.	List to query (a multi-line field)
In list (substring match)	Says whether the value contains one of the expressions in the list or not.	List to query (a multi-line field)
In list (IP/cidr match)	Says whether the IP address enters the addresses or blocks in the list or not.	List to query (a multi-line field)
In list (beginning match)	Says whether the value begins with one of the expressions in the list or not.	List to query (a multi-line field)
In list (ending match)	Says whether the value ends with one of the expressions in the list or not.	List to query (a multi-line field)

The List and Mapping Fields

In the list functions the content to be compared is not selected from a list object defined separately; it is written directly into the argument field of the function. While TR7 is producing the configuration, it writes this content to its own file and makes the comparison over that file.

Function type	What is written into the argument field
In list	The values to be looked for; they are separated with a space or with a line end. The result is 1 in a match and 0 if there is no match
Mapping	In every row first the key, then a space, then its correspondence. The rows that do not have a correspondence are not taken into account; if no row matches, the result is empty

The Option Lists

The ready list of Hash algorithm (md5,sha256,...) (22)

blake2b512, blake2s256, gost, md2, md4, md5, mdc2, rmd160, sha1, sha224, sha256, sha3-224, sha3-256, sha3-384, sha3-512, sha384, sha512, sha512-224, sha512-256, shake128, shake256, sm3

The field accepts free text; the list is offered only as a suggestion.

The MQTT field name options

While MQTT packet type is CONNECT (23): flags, protocol_name, protocol_version, client_identifier, will_topic, will_payload, username, password, keepalive, 1, 2, 3, 8, 9, 17, 18, 21, 22, 23, 25, 33, 34, 39

While MQTT packet type is CONNACK (19): flags, protocol_version, reason_code, 17, 18, 19, 21, 22, 26, 28, 31, 33, 34, 36, 37, 39, 40, 41, 42

The FIX tag options (405 unique tags)

Account, AdvId, AdvRefID, AdvSide, AdvTransType, AvgPx, BeginSeqNo, BeginString, BodyLength, CheckSum, ClOrdID, Commission, CommType, CumQty, Currency, EndSeqNo, ExecID, ExecInst, ExecRefID, ExecTransType, HandlInst, IDSource, IOIid, IOIOthSvc, IOIQltyInd, IOIRefID, IOIShares, IOITransType, LastCapacity, LastMkt, LastPx, LastShares, LinesOfText, MsgSeqNum, MsgType, NewSeqNo, OrderID, OrderQty, OrdStatus, OrdType, OrigClOrdID, OrigTime, PossDupFlag, Price, RefSeqNum, RelatdSym, Rule80A, SecurityID, SenderCompID, SenderSubID, SendingDate, SendingTime, Shares, Side, Symbol, TargetCompID, TargetSubID, Text, TimeInForce, TransactTime, Urgency, ValidUntilTime, SettlmntTyp, FutSettDate, SymbolSfx, ListID, ListSeqNo, TotNoOrders, ListExecInst, AllocID, AllocTransType, RefAllocID, NoOrders, AvgPrxPrecision, TradeDate, ExecBroker, OpenClose, NoAllocs, AllocAccount, AllocShares, ProcessCode, NoRpts, RptSeq, CxlQty, NoDlvyInst, DlvyInst, AllocStatus, AllocRejCode, Signature, SecureDataLen, SecureData, BrokerOfCredit, SignatureLength, EmailType, RawDataLength, RawData, PossResend, EncryptMethod, StopPx, ExDestination, CxlRejReason, OrdRejReason, IOIQualifier, WaveNo, Issuer, SecurityDesc, HeartBtInt, ClientID, MinQty, MaxFloor, TestReqID, ReportToExch, LocateReqd, OnBehalfOfCompID, OnBehalfOfSubID, QuoteID, NetMoney, SettlCurrAmt, SettlCurrency, ForexReq, OrigSendingTime, GapFillFlag, NoExecs, CxlType, ExpireTime, DKReason, DeliverToCompID, DeliverToSubID, IOINaturalFlag, QuoteReqID, BidPx, OfferPx, BidSize, OfferSize, NoMiscFees, MiscFeeAmt, MiscFeeCurr, MiscFeeType, PrevClosePx, ResetSeqNumFlag, SenderLocationID, TargetLocationID, OnBehalfOfLocationID, DeliverToLocationID, NoRelatedSym, Subject, Headline, URLLink, ExecType, LeavesQty, CashOrderQty, AllocAvgPx, AllocNetMoney, SettlCurrFxRate, SettlCurrFxRateCalc, NumDaysInterest, AccruedInterestRate, AccruedInterestAmt, SettlInstMode, AllocText, SettlInstID, SettlInstTransType, EmailThreadID, SettlInstSource, SettlLocation, SecurityType, EffectiveTime, StandInstDbType, StandInstDbName, StandInstDbID, SettlDeliveryType, SettlDepositoryCode, SettlBrkrCode, SettlInstCode, SecuritySettlAgentName, SecuritySettlAgentCode, SecuritySettlAgentAcctNum, SecuritySettlAgentAcctName, SecuritySettlAgentContactName, SecuritySettlAgentContactPhone, CashSettlAgentName, CashSettlAgentCode, CashSettlAgentAcctNum, CashSettlAgentAcctName, CashSettlAgentContactName, CashSettlAgentContactPhone, BidSpotRate, BidForwardPoints, OfferSpotRate, OfferForwardPoints, OrderQty2, FutSettDate2, LastSpotRate, LastForwardPoints, AllocLinkID, AllocLinkType, SecondaryOrderID, NoIOIQualifiers, MaturityMonthYear, PutOrCall, StrikePrice, CoveredOrUncovered, CustomerOrFirm, MaturityDay, OptAttribute, SecurityExchange, NotifyBrokerOfCredit, AllocHandlInst, MaxShow, PegDifference, XmlDataLen, XmlData, SettlInstRefID, NoRoutingIDs, RoutingType, RoutingID, SpreadToBenchmark, Benchmark, CouponRate, ContractMultiplier, MDReqID, SubscriptionRequestType, MarketDepth, MDUpdateType, AggregatedBook, NoMDEntryTypes, NoMDEntries, MDEntryType, MDEntryPx, MDEntrySize, MDEntryDate, MDEntryTime, TickDirection, MDMkt, QuoteCondition, TradeCondition, MDEntryID, MDUpdateAction, MDEntryRefID, MDReqRejReason, MDEntryOriginator, LocationID, DeskID, DeleteReason, OpenCloseSettleFlag, SellerDays, MDEntryBuyer, MDEntrySeller, MDEntryPositionNo, FinancialStatus, CorporateAction, DefBidSize, DefOfferSize, NoQuoteEntries, NoQuoteSets, QuoteAckStatus, QuoteCancelType, QuoteEntryID, QuoteRejectReason, QuoteResponseLevel, QuoteSetID, QuoteRequestType, TotQuoteEntries, UnderlyingIDSource, UnderlyingIssuer, UnderlyingSecurityDesc, UnderlyingSecurityExchange, UnderlyingSecurityID, UnderlyingSecurityType, UnderlyingSymbol, UnderlyingSymbolSfx, UnderlyingMaturityMonthYear, UnderlyingMaturityDay, UnderlyingPutOrCall, UnderlyingStrikePrice, UnderlyingOptAttribute, Underlying, RatioQty, SecurityReqID, SecurityRequestType, SecurityResponseID, SecurityResponseType, SecurityStatusReqID, UnsolicitedIndicator, SecurityTradingStatus, HaltReason, InViewOfCommon, DueToRelated, BuyVolume, SellVolume, HighPx, LowPx, Adjustment, TradSesReqID, TradingSessionID, ContraTrader, TradSesMethod, TradSesMode, TradSesStatus, TradSesStartTime, TradSesOpenTime, TradSesPreCloseTime, TradSesCloseTime, TradSesEndTime, NumberOfOrders, MessageEncoding, EncodedIssuerLen, EncodedIssuer, EncodedSecurityDescLen, EncodedSecurityDesc, EncodedListExecInstLen, EncodedListExecInst, EncodedTextLen, EncodedText, EncodedSubjectLen, EncodedSubject, EncodedHeadlineLen, EncodedHeadline, EncodedAllocTextLen, EncodedAllocText, EncodedUnderlyingIssuerLen, EncodedUnderlyingIssuer, EncodedUnderlyingSecurityDescLen, EncodedUnderlyingSecurityDesc, AllocPrice, QuoteSetValidUntilTime, QuoteEntryRejectReason, LastMsgSeqNumProcessed, OnBehalfOfSendingTime, RefTagID, RefMsgType, SessionRejectReason, BidRequestTransType, ContraBroker, ComplianceID, SolicitedFlag, ExecRestatementReason, BusinessRejectRefID, BusinessRejectReason, GrossTradeAmt, NoContraBrokers, MaxMessageSize, NoMsgTypes, MsgDirection, NoTradingSessions, TotalVolumeTraded, DiscretionInst, DiscretionOffset, BidID, ClientBidID, ListName, TotalNumSecurities, BidType, NumTickets, SideValue1, SideValue2, NoBidDescriptors, BidDescriptorType, BidDescriptor, SideValueInd, LiquidityPctLow, LiquidityPctHigh, LiquidityValue, EFPTrackingError, FairValue, OutsideIndexPct, ValueOfFutures, LiquidityIndType, WtAverageLiquidity, ExchangeForPhysical, OutMainCntryUIndex, CrossPercent, ProgRptReqs, ProgPeriodInterval, IncTaxInd, NumBidders, TradeType, BasisPxType, NoBidComponents, Country, TotNoStrikes, PriceType, DayOrderQty, DayCumQty, DayAvgPx, GTBookingInst, NoStrikes, ListStatusType, NetGrossInd, ListOrderStatus, ExpireDate, ListExecInstType, CxlRejResponseTo, UnderlyingCouponRate, UnderlyingContractMultiplier, ContraTradeQty, ContraTradeTime, ClearingFirm, ClearingAccount, LiquidityNumSecurities, MultiLegReportingType, StrikeTime, ListStatusText, EncodedListStatusTextLen, EncodedListStatusText

Notes

• More than one function is added to a variable; the ordering changes the result.
• In the HMAC signature function the HMAC key format field states in which form the key is written. The key in the hex and text forms is converted to Base64 while the configuration is being produced; the key in the base64 form is used as it is. Of the options of this field, base64 and hex appear in the interface as the dictionary key and text as Text.
• In the Replace (first) and Replace (all) functions, if New value is left empty, the part that matches is deleted. The To replace field is a regular expression; e.g. . matches any character.
• All three fields of the Split text function are required and do not have a default value.
• The IP masking function takes a single mask value and this value is applied to the IPv4 addresses; on the IPv6 addresses masking is not made. Even though the form accepts the range 0-128, the values above 32 lead to a configuration error.
• The Summary row of the window shows in a readable form what the result means together with the functions selected. In the row the short form is written; when it is hovered over, the long form opens as a tooltip. The summary explains only the first ten functions; the following functions do not appear in the summary.