Composing Messages
CXIO messages are composed using info command objects. These objects require a kind descriptor consisting of alphanumeric characters and must conclude with an ends closure directive. The purpose of the kind descriptor is to enable the receiving system to identify, route, and process messages, while also providing readable context for users. In the examples shown below, and throughout these guides, the kind descriptor is set as "invoice" for illustrative purposes only.
info invoice ends
An identifier can be specified using the is decorator, and a subject can be provided using the as decorator.
info invoice is "invoice001" as "invoice for goods supplied" ends
Whitespace separates command elements, meaning instructions can be written as a single line and with indentation as needed.
info invoice ends
Processing tokens which are commands, directives and decorators are case insensitive.
INFO invoice ENDS
Header Directives
Header information including addressing, metadata and message references is provided using directives such as from, recv, addr, meta and code. These header directives should always precede any message directives.
info invoice from tradesuppliers recv plumbingco code inv20010624 ends
It is recommended that header directive values are single alphanumeric values. Double quotes are not required, however are supported. The use of whitespace within header directive values should be avoided where possible, with the exception of meta data as explained later in this guide.
Header Grouping
To assist with readability and processing, header directives may be grouped within a head directive and close with the ends directive as shown below.
info invoice
head
from tradesuppliers
recv plumbingco
code inv20010624
ends
ends
Addressing Directives
Addressing directives, which are specifically from (the sender), recv (the receiver) and addr (additional parties) may contain meta data to assist with message routing, processing and administrative support. This is achieved using with directives, as shown below. The addressing directives must always be closed with an ends directive where it contains meta data.
info invoice
recv plumbingco
with email as "buyer@plumingandco.net"
with telephone as "+23 00011122341"
ends
from tradesuppliers
with email as "admin@tradesuppliers.net"
with telephone as "+44 00011122342"
ends
addr expresslogistics is notifyparty
with email as "admin@expresslogistics.net"
with telephone as "+44 00011122345"
ends
ends
The at sign @ can be used as shorthand alternative for with directives, as shown below.
info invoice
recv plumbingco
@email: "buyer@plumingandco.net"
@telephone: "+23 00011122341"
ends
ends
The is identity decorator can be used with addr directives to identify the type of addressee. In the case of from and recv directives, the default addressee type is sender and receiver accordingly and should not be overridden. The as subject decorator can be applied against from, recv and addr directives to provide a descriptive of the addressee.
addr expresslogistics is notifyparty as "Express Logistics Network"
with email as "admin@expresslogistics.test"
with telephone as "+44 00011122345"
ends
recv plumbingco as "Plumbing & Co LTD"
with email as "buyer@plumingandco.test"
with telephone as "+23 00011122341"
ends
from tradesuppliers as "Global Trade Suppliers PLC"
with email as "admin@tradesuppliers.test"
with telephone as "+44 00011122342"
ends
Messaging Directives
Message content is conveyed using body, line and item directives, as shown below. Body and line directives must always be closed using the ends directives.
info invoice
recv plumbingco
from tradesuppliers
code inv20010624
body
item total as 10.00
item reference as "supply of goods"
item cashondelivery as true
item reserved as null
line tax
item amount as 2.00
item rate as 1.20
ends
ends
ends
It is possible to use item shorthand as an alternative to item directives, by specifying a colon : directly after the item name, as shown below. When using item shorthand, a value must be given immediately after the item name. Where there is no value, null should be specified.
info invoice
body
total: 12.00
reference: "supply of goods"
cashondelivery: true
reserved: null
line tax
amount: 2.00
rate: 1.20
ends
ends
ends
Message Body
For single messages within the instruction, the body directive is not strictly required, as the presence of line or item directives indicates that the message body has started. For readability, it is recommended practice to use the body directive.
info invoice
recv plumbingco
from tradesuppliers
code inv20010624
item total as 10.00
item reference as "supply of goods"
item cashondelivery as true
line tax
item amount as 2.00
item rate as 1.20
ends
ends
Multi body
Where there is more than one message within the instruction, multiple body directives can be specified to separate the messages, as shown below. The is decorator can be used to assign an identify to each message, and as can be used to provide a subject.
info invoice as "weekly invoices"
body is invoice01 as "first invoice"
total: 846.23
reference: "supply of goods - invoice 1"
cashondelivery: true
ends
body is invoice02 as "second invoice"
total: 178.62
reference: "supply of goods - invoice 2"
cashondelivery: false
ends
ends
Message Kinds
All messages within the instruction shall inherit the info kind descriptor unless overridden within the kind decorator against the body.
info batch
head
recv plumbingco
from tradesuppliers
ends
body kind order
....
ends
body kind invoice
....
ends
ends
Multi-Part Messages
Messages can be grouped together within part directives. Each part may have its own header information (including addressing and metadata directives) and multiple message bodies, as shown below.
info batch
from tradesuppliers
part is part1 as "first message batch"
recv invoiceparty1
body is invoice01 as "first invoice"
total: 846.23
reference: "supply of goods - invoice 1"
ends
body is invoice02 as "second invoice"
total: 178.62
reference: "supply of goods - invoice 2"
ends
ends
part is part2 as "second message batch"
recv invoiceparty2
body is invoice03 as "third invoice"
total: 12.62
reference: "supply of goods - invoice 3"
ends
ends
ends