Pdf file - Babelway

Transcription

Pdf file - Babelway

Babelway B2B Integration Platform
Documentation
Self-service help
Babelway B2B Integration Platform Documentation
Copyright © 2012 Babelway
Table of Contents
1. Introduction - Babelway concept .................................................................................................... 1
2. Generalities .................................................................................................................................. 2
2.1. Login and registration ................................................................................................. 2
2.2. Page structure ............................................................................................................ 3
2.3. Finding help ............................................................................................................... 4
2.4. Grids ......................................................................................................................... 6
2.4.1. Filters ..................................................................................................................... 7
3. Monitoring ................................................................................................................................. 12
3.1. Messages ................................................................................................................. 12
3.1.1. Messages list ......................................................................................................... 12
3.1.2. Message details ..................................................................................................... 13
3.1.3. Resubmitting a Message ........................................................................................ 21
3.1.4. Resubmit multiple messages .................................................................................. 22
3.1.5. Download messages as a zip file ............................................................................. 23
3.1.6. Verify a message integrity ...................................................................................... 25
3.2. Alerts ...................................................................................................................... 26
3.2.1. Alerts list .............................................................................................................. 27
3.2.2. Alert details .......................................................................................................... 27
3.2.3. All possible alerts types ......................................................................................... 28
3.3. Statistics .................................................................................................................. 30
3.3.1. Status statistics ...................................................................................................... 30
3.3.2. Time evolution statistics ........................................................................................ 32
3.3.3. Traffic shape statistics ........................................................................................... 34
3.4. Documents .............................................................................................................. 36
4. Channels .................................................................................................................................... 37
4.1. Overview ................................................................................................................. 37
4.1.1. Channels list ......................................................................................................... 38
4.1.2. Creation of a new Channel ..................................................................................... 39
4.1.3. Channel detail ....................................................................................................... 39
4.1.4. Deployment .......................................................................................................... 43
4.1.5. Delete a Channel ................................................................................................... 44
4.1.6. Duplicate a Channel .............................................................................................. 45
4.2. Gateways ................................................................................................................. 46
4.2.1. Gateways list ......................................................................................................... 46
4.2.2. Creation of a gateway ............................................................................................ 47
4.2.3. Gateway detail ...................................................................................................... 50
4.2.4. Gateway types ....................................................................................................... 52
4.3. Message definitions ................................................................................................ 110
4.3.1. Message definitions list ........................................................................................ 110
4.3.2. Creation of a message definition ........................................................................... 111
4.3.3. Message definition detail ..................................................................................... 114
4.3.4. Update the message definition tree ........................................................................ 115
4.3.5. Message definition formats .................................................................................. 128
4.3.6. Common Message Definition Properties ............................................................... 153
4.4. Transformations ..................................................................................................... 154
4.4.1. Transformations list ............................................................................................. 154
4.4.2. Creation of a transformation ................................................................................. 155
4.4.3. Transformation detail ........................................................................................... 155
ii
Babelway Help Guide
4.4.4. Drag and Drop Transformation ............................................................................. 157
4.4.4.1. Viewing and selecting mapping rules. ........................................................ 157
4.4.4.2. Nodes mapping ......................................................................................... 160
4.4.4.3. Edit formula ............................................................................................. 161
4.4.4.4. Understanding functions ............................................................................ 165
4.4.4.5. User-defined functions .............................................................................. 168
4.4.4.6. Sub-formulas ............................................................................................ 171
4.4.4.7. Working with formulas - frequent scenarios ............................................... 174
4.4.4.8. Mapping loops .......................................................................................... 179
4.4.4.9. Multi nodes mapping ................................................................................ 182
4.4.4.10. Using or changing metadata ..................................................................... 184
4.4.4.11. Drag and Drop transformation properties .................................................. 185
4.4.5. Xslt Transformation ............................................................................................. 186
4.4.6. No Transformation .............................................................................................. 187
4.5. Notifications .......................................................................................................... 188
4.5.1. Notifications list .................................................................................................. 188
4.5.2. Notification detail ................................................................................................ 189
4.6. Partners ................................................................................................................. 193
4.6.1. Defining partners manually .................................................................................. 193
4.6.2. Assigning partners to messages ............................................................................ 196
4.6.3. Creating your partners from messages ................................................................... 198
4.6.4. Using partners ..................................................................................................... 200
4.6.5. Be compliant to GS1. ........................................................................................... 202
4.6.6. Automatic Population of your Partners List ........................................................... 203
4.7. Lookup tables ........................................................................................................ 204
4.7.1. Lookup tables list ................................................................................................ 204
4.7.2. Create a lookup table ........................................................................................... 205
4.7.3. Lookup table detail .............................................................................................. 206
4.7.4. Use your lookup tables. ........................................................................................ 210
4.7.5. Automatic Population of Lookup table from CSV .................................................. 210
4.7.6. Automatic Population of Lookup table using Channel ............................................ 211
4.8. Routing ................................................................................................................. 213
4.8.1. Routings list ........................................................................................................ 213
4.8.2. Routings detail .................................................................................................... 214
4.8.3. Edition of routings from channels section .............................................................. 215
4.9. Test cases .............................................................................................................. 216
4.9.1. Test case detail .................................................................................................... 219
4.10. Certificates .......................................................................................................... 219
4.10.1. Certificate's Details ............................................................................................ 221
4.10.2. Trust new certificate .......................................................................................... 221
4.10.3. Add a certificate ................................................................................................ 222
4.11. Extra processings ................................................................................................. 222
4.11.1. Extra processings on gateway IN ........................................................................ 224
4.11.2. Extra processings on message definition IN ......................................................... 225
4.11.3. Extra processings on Transformation .................................................................. 229
4.11.4. Extra processings on message definition OUT ..................................................... 229
4.11.5. Extra processings on gateway OUT .................................................................... 236
4.12. Metadata .............................................................................................................. 236
4.12.1. Metadata usage .................................................................................................. 237
4.12.2. System Metadata ............................................................................................... 240
4.13. Change Log ......................................................................................................... 242
4.13.1. Environment change Log ................................................................................... 242
iii
Babelway Help Guide
4.13.2. Elements change Log ......................................................................................... 243
4.14. Reuse and save time ............................................................................................. 243
4.14.1. Search and Reuse ............................................................................................... 244
4.14.2. Using the Babelway catalogue ............................................................................ 246
4.14.3. Using or duplicating elements that you already defined. ....................................... 247
4.14.4. Accessing elements from other environments. ..................................................... 248
4.14.5. Using examples or suggestions. .......................................................................... 249
5. Admin ...................................................................................................................................... 250
5.1. Personal data .......................................................................................................... 250
5.2. Environment settings .............................................................................................. 251
5.2.1. General ............................................................................................................... 252
5.2.2. Messages ............................................................................................................ 253
5.2.3. Partners .............................................................................................................. 254
5.2.4. Document types .................................................................................................. 255
5.2.5. Do I need one or several account environments ? ................................................... 257
5.3. Billing ................................................................................................................... 259
5.4. Users ..................................................................................................................... 259
5.4.1. Add a User .......................................................................................................... 260
5.4.2. User detail .......................................................................................................... 261
6. Miscellanous ............................................................................................................................ 263
6.1. B2B Integration Project Management ...................................................................... 263
6.2. DNS load-balancing ............................................................................................... 264
6.3. External References ................................................................................................ 265
6.4. Rest API ................................................................................................................ 267
6.4.1. Introduction ........................................................................................................ 267
6.4.2. Available actions ................................................................................................. 267
6.4.2.1. tickets ...................................................................................................... 268
6.4.2.2. ticket ........................................................................................................ 269
6.4.2.3. deleteTicket .............................................................................................. 270
6.4.2.4. messages .................................................................................................. 270
6.4.2.5. message ................................................................................................... 272
6.4.2.6. channels ................................................................................................... 273
6.4.2.7. gateways .................................................................................................. 275
6.4.2.8. messageDefinitions ................................................................................... 276
6.4.2.9. transformations ......................................................................................... 277
6.4.2.10. catalogue ................................................................................................ 278
6.4.3. Code samples ...................................................................................................... 278
6.5. BabelInvoice .......................................................................................................... 281
6.5.1. BabelInvoice Solution .......................................................................................... 282
6.5.2. Install BabelInvoice for PDFCreator ..................................................................... 283
6.5.3. Using BabelInvoice for Stand alone ...................................................................... 292
6.5.4. BabelInvoice Setting ............................................................................................ 293
6.6. Verify yourself the chain ........................................................................................ 296
iv
1
Introduction - Babelway concept
Babelway is a B2B integration Software-as-a-Service-SaaS. Babelway provides a data translation software and
B2B communication gateways organised in a full-service proposition. Babelway services are fully available ondemand via a web-browser. There is no software or hardware to buy and maintain in-house, however Babelway
is still under the full control of its users.
The main functions of Babelway are:
• Babelway transports electronic messages between two parties.
• Babelway transforms messages from an input to an output format (csv, xml, Excel, flat file, EDI,...).
• Babelway stores messages in a secure way for a defined period of time. The archiving system is compliant
with EU legal requirements.
The following video is an introduction to the application:
1
2
Generalities
In this chapter, we explain the structure of the interface, and all other topics that are transversal to the application, such as style conventions or grids.
2.1. Login and registration
To access the application, just go to the url https://www.babelway.net/.
Figure 2.1. Login page
If you are already a registered user, just fill in your login and password details in the left part of the screen.
If you are not yet a registered user, enter your email in the right part of the screen, and choose a username and a
password. A new environment will be created for you and you will be able to test the application FREE for 30
days.
Reset Password
If you don't remember your username or your password, you can follow the 'Forgot your password?' link. This
will lead you to the 'Reset Password' page.
Start by entering the email address you used to register your account in Babelway. The system will then send
2
Generalities
you an email containing a link to a secure page allowing you to reset your password. Note: That if you have registered several users with the same email address, the system will offer you the choice of which one you want
to change.
Expired Password
If your password expired, you will automatically be redirected to the 'Renew expired password' page. You will
not be able to access Babelway until your password is renewed.
2.2. Page structure
All the pages of the application have the following elements (see figure):
Figure 2.2. Page structure
• The goal of the top bar is to show you in which environment you are working. It displays:
• Name of the current user.
• The environment you are working in. This is only available if you have access to multiple environments.
In this case, you can also switch from one environment to another (just click on the arrow at the right of
the name of the environment).
• The help menu. See help for more details.
• A logout button.
• The menu allows you to go to the different parts of the application
• Home just allows you to return to the welcome page of the application.
3
Generalities
• You'll find in the Monitoring section all the functionalities needed to follow and manage all the messages
processed by the system, once the flow of messages is defined.
• In the Channels section, you'll be able to define how the messages will be processed by the system.
• The Admin section gives you access to the parameters of your environments, your bills, the management
of the users that may access your account, ...
• The page introduction is a short inline help for the page. See help for more details.
• The page title and page body contains the data of the page, and are specific to each page.
• The feedback button allows you to easily contact Babelway. It is also described in more details in the help
section.
2.3. Finding help
In the interface, you will find many methods to get help. Most of this help is available via the help menu, which
can be found right of the top bar.
Figure 2.3. Page structure
• Page introduction. At the begining of every page, a short text gives you contextual help about the page.
Figure 2.4. Page introduction
If you don't want to see it anymore, just close it by clicking the X which can be found in the upper-right
corner of this zone, and it will also not be displayed anymore for all the following pages. Only a small image
will remain, in place of the X, which will allow you to make it appear again if you want.
• In many places of the application, inline help is available. It is indicated by the icon
. To see the help, just
place your mouse over the icon.
4
Generalities
Figure 2.5. Inline help
• Help. This is a help manual, available via the help menu.
• Support. If you have any question, don't hesitate to ask at [email protected]. We'll answer you
promptly. The link is also accessible via the help menu.
• Babel Academy. Training given by an expert user of Babelway. Click in the help menu to access.
• Tutorial. The tutorial is a good way to learn the basics of the interface. You can launch the tutorial by clicking on the tutorial option in the help menu.
• Feedback. If at any time, you experience a problem, or just have some feedback or suggestion about the interface, you can send it to us by clicking the feedback button,which can be found at the bottom-right of the
interface.
Figure 2.6. Feedback
5
Generalities
2.4. Grids
Grids of data are displayed in many pages of the application.
The grids are very powerful, and have many options that are described below.
The grids are always displayed as in the following figure:
Figure 2.7. Grids
• The headers contain the title of the column.
On most columns, you can click on it to sort the data following this column. If you want to sort in the reverse
order, you click again on the header of the column. The current sort of the grid is signified by the icon
You can resize columns by clicking on the separation between two columns, and dragging the icon to the
preferred size.
You can also reorder columns by clicking on the header of one column, and dragging it to the new place you
want.
• The filter bar allows you to filter the displayed data.
The system will only display the data that satisfies ALL the criteria that you enter in this line.
You can find more information about the specific filters available for all columns in the Filters section.
• The data zone just displays the requested data.
• The zone with the number of data tells you how many records have matched your criteria, and which part of
this data is currently displayed.
• With the Pagination options, you can easily navigate in all the data, or choose the number of records that you
want to display on a page. The system will automatically record this preference when you change it, and subsequently display by default all the next tables with this number of records.
• The action buttons allow you to complete the following actions:
•
allows you to change the displayed columns.
•
6
Generalities
allows you to clear all search criteria.
•
allows you to refresh the data.
•
allows you to export the data.
2.4.1. Filters
In all grids, the filter bar allows you to filter easily the displayed data.
The filters that are available depends on the type of data in this column. If you use multiple criteria, the system
will display the data that satisfies ALL the criteria. You can also reset all the criteria in one click with the "Reset filters" buttton found in the action buttons of the grid.
Textual data
For textual data (columns like name, description ...), you will have a text-field allowing you to type your criteria. The system will search for all the data that contains the criteria.
Figure 2.8. Textual filter
Types with a limited number of possible values.
When all the values of type can be enumerated, you will have a dropdown showing all the possible values. The
system will search for all the data that have (exactly) this value in this column.
7
Generalities
Figure 2.9. Filter on a date
Dates and times
You will have a dropdown allowing you to choose from several common periods ("Last 24 hours", "Last 7
days", "Last month", ...)
Figure 2.10. Filter on a closed type
8
Generalities
If you have more unusual needs, you can select the "Custom" value. A popup will then be available where you
will be able to choose any time interval.
Figure 2.11. Custom filter on a date
Channels, gateways, message definitions, transformations, ...
For all columns referring to one of the elements of your environment, you will have a text-field (with autocomplete).
The following values can be used in the field:
• =<id>: the system will filter on the elements that have this precise id.
• =<name>: the system will filter on the elements that have (exactly) this name.
• <name>: the system will filter on the elements whose name contains the criteria.
9
Generalities
Figure 2.12. Filter on a channel
Ids
For the columns containing the id of an element, you will have a text field.
The following values can be used in the field:
• <id> : the system will filter on the elements that have this precise id.
• Comma separated list of ids: the system will filter on the elements that have one of these ids.
Figure 2.13. Filter on an id
Other numeric values
For the numeric columns, you will have a text field.
The following values can be used in the field :
• N: the system will filter on the elements that have exactly this value N in this column.
• <N: the system will filter on the elements whose value is (stricly) smaller than N.
• <=N: the system will filter on the elements whose value is smaller than, or equal to N.
10
Generalities
• >N: the system will filter on the elements whose value is (stricly) greather than N.
• >=N: the system will filter on the elements whose value is greather than, or equal to N.
• Comma separated list of any criteria above: all the criteria will be applied.
Figure 2.14. Filter on a numeric column
11
3
Monitoring
The monitoring section of the application contains all the tools and information that allows you to follow and
manage the messages processed by the system, once the rules for how to handle the messages have been setup.
The main functionalities are:
• Search in all messages processed by the system. See all the details of the messages.
• View the alerts generated by the system.
• Actions to manage the messages (for example, resubmit a message in error)
• View stats on the messages.
• View documents, a business view on the processed messages.
Note
The items in the previous list should link to the section that details the functionality.
3.1. Messages
A message encapsulates all the information about the processing of an input file of data by the Babelway system.
The message contains the following information:
• The incoming file: The file received by Babelway from the source external system.
• The outgoing file: The file sent by Babelway to the target external system.
• The status of the processing: Was the file correctly processed or was it in error? It it still being processed?
• Various dates about the processing: When was the input file received, when was the output sent, ...
• Information about how the message was received or sent.
• ...
3.1.1. Messages list
The list of messages allows you to browse and search all messages processed by the Babelway systems.
To access this screen, just click on the Monitoring menu item. The Messages sub-menu item is automatically
selected.
12
Monitoring
Figure 3.1. List of messages
Many information about the messages can be directly displayed in the grid. The detailed explanation of each
possible information can be found in message details.
For more information about the behavior of the grid, and how to make searches, see the grid section of the help.
Click on a message line to access its all the details about the message, and be able to make actions on it.
3.1.2. Message details
The message details screen shows you all the details about the processing of a message by the Babelway system. It also allows you to make all necessary actions on this message.
You can access it by clicking on a line in the messages list screen, or just by clicking on it every time a reference to a message is displayed.
13
Monitoring
Figure 3.2. Message details screen
The following information can be available on a message:
14
Monitoring
Status
The status of the message processing. The possible statuses are:
• Processing: When the message is being processed by Babelway.
• Paused: The message processing was temporarily stopped (because human validation has been requested,
because it can only be delivered in specific time frames, ...).
• In delivery: When the message is being transferred to the target system. This status differs from "In progress" in the sense that output message is completely generated and available via the interface, but communication of the message to the target system is not yet terminated. The reasons for this delay in the
communication can be multiple: We wait for the file being downloaded, or we wait for an acknowledgment, or the target system was unavailable and we will retry later, ...
• Success: When the message processing is completely finished and everything happened as requested.
• Error: When the message processing is completely finished and there was an error in any step of the processing.
Here are some examples of errors:
• The received file did not pass the input validations.
• The generation of the output file completed successfully, the file was made available for download on
Babelway FTP server, but was never downloaded (after X days). This is an error because we know
that the file was not received by the end user.
• The generation of the output file completed successfully and the file had to be sent by email to 2 recipients. One of the delivery succeeded (and the user) correctly received the message), while the other delivery failed.
• The generation of the output file completed successfully and was correctly uploaded to the target system, but we did not receive an expected acknowledgement (or it was not correct).
• The processing crashed.
The precise description of the error will always be present in the field "Error description"
• Error (closed): This status will never be used automatically by the system, but allows you to mark the errors that you already have analyzed and fixed.
Date in
The date and time when the message was received by Babelway.
Date out
The date and time when the processing of the message was completely finished (even if complete processing of the message implied waiting for an acknowledgement from the external system, waiting for
download by the client, making retries,etc.).
Processing complete
The date and time when the Babelway processing of the message was finished. This is the moment when
the message out is made available to the target system.
This time will differ from "Date out" when the delivery of the file implies waiting for the external target
system (ex: waiting for an acknowledgement, waiting for a download, or waiting for the external system
15
Monitoring
availability). "Processing complete" doesn't include this delay while "Date out" includes this delay.
Keep until
The date and time until which the message will be kept in the Babelway system. You can change this setting for your whole environment or by channel.
Message In
Incoming file, as received by the source external system. Click on the file name to open it. Click on the
lock to display the Security info.
Message Out
Outgoing file, as sent to the target external system. In case of processing error, this file may be unavailable
if the messaging engine was unable to generate it. Click on the file name to open it. Click on the lock to
display the Security info.
Error description
When the message couldn't be processed, a text that describes the error's reason.
Type
Message type, can be either Test or Regular.
Test status
Only for test messages. The test status, can be either Test failed, Waiting result or Test successful. It should
be differentiated from the Status field, that tells if the message has been processed without errors. When
you make a test case, you can add complementary assertions on the result of the processed message. This
will cause the test to be considered as 'failed' if not fulfilled.
Channel
The channel that processed the message.
Gateway In
Incoming gateway used to receive the input file.
Gateway Out
Outgoing gateway used to process the input file.
Key
A uuid (universal unique identifier) that uniquely identifies a Message.
Reference
Message reference or file name. You can choose this reference.
Gateway in message key
Specific communication-level identifier from the gateway in.
Gateway in message status
Specific communication-level information from the gateway in, like related id's or addressing information
of partner systems
Gateway out message key
Specific communication-level identifier from the gateway out
Gateway out message status
Specific communication-level information from the gateway out, like related id's or addressing information
of partner systems, info about acknowledgments, retries, ...
16
Monitoring
Size of incoming message
Incoming message size (in bytes).
Size of outgoing message
Outgoing message size (in bytes).
User comment
Free text allowing the user to comment on a message. It can be changed anytime from the SelfService applicaiton as well as during in the processing of any message.
The section Internal files also gives you access to internal data about the processing of the message. This information can be useful to investigate some problems, or to understand the behavior of the system. Two categories of internal files exist: The step files and the other files.
The step files represent the evolution of the message content from the message IN to the message OUT. After
each modification of the message's content, a new step file is created. Here is the complete list of possible types
of step files:
Message IN after unwrapping (Deprecated)
The message IN after the deprecated unwrapping extra-processing.
Message IN after S/MIME unwrapping
The message IN after the S/MIME unwrapping extra-processing.
Message IN after PGP unwrapping
The message IN after the PGP unwrapping extra-processing.
Message IN after ZIP unwrapping
The message IN after the ZIP unwrapping extra-processing.
Message IN after PDF unwrapping
The message IN after the PDF unwrapping extra-processing.
Message IN after regular expression transformation
The message IN after the regular expression based extra-processing.
Message IN after Serving XML transformation
The message IN after the Serving XML based extra-processing.
Message IN after transformation to XML
The message IN after its conversion to an internal XML representation.
Message IN after XSLT transformation
The XML message IN after the XSLT based extra-processing.
Message after transformation
The XML message after its transformation.
Message OUT after XSLT transformation
The XML message OUT after the XSLT based extra-processing.
Message OUT after transformation from XML
The message OUT after its conversion from the internal XML representation.
Message OUT after Serving XML transformation
17
Monitoring
The message OUT after the Serving XML based extra-processing.
Message OUT after regular expression transformation
The message OUT after the regular expression based extra-processing.
Message OUT after line delimiter transformation
The message OUT after the line delimiter transformation extra-processing.
Message OUT after PDF wrapping
The message OUT after the PDF wrapping extra-processing.
Message OUT after ZIP wrapping
The message OUT after the ZIP wrapping extra-processing.
Message OUT after PGP wrapping
The message OUT after the PGP wrapping extra-processing.
Message OUT after S/MIME wrapping
The message OUT after the S/MIME wrapping extra-processing.
The other files represent the additional information (other than the content) produced during the message processing. Here is the complete list of possible types of other files:
Context in
Full context of execution of the message, as it was at the start of the processing (after reception by the gateway IN).
Context out
Full context of execution of the message, as it was at the end of the processing.
Context
Additional list of properties and log of processes applied during message processing.
Message Delivery Notification In (MDN In)
The Message Delivery Notification (MDN) that was sent to the caller, to prove that Babelway has received
the message.
Message Delivery Notification Out (MDN Out)
The Message Delivery Notification (MDN Out) that was received from the receiver of the message, to
prove that Babelway has correctly submitted the message to its destination.
Documents In
When a document extractor is used on MessageDefinition IN, the extracted documents.
Documents Out
When a document extractor is used on MessageDefinition OUT, the extracted documents.
Invoices In
When a document extractor is used on MessageDefinition IN, the extracted invoices.
Invoices Out
When a document extractor is used on MessageDefinition OUT, the extracted invoices.
Orders In
When a document extractor is used on MessageDefinition IN, the extracted orders.
18
Monitoring
Orders Out
When a document extractor is used on MessageDefinition OUT, the extracted orders.
Desadvs In
When a document extractor is used on MessageDefinition IN, the extracted dispatch advices.
Desadvs Out
When a document extractor is used on MessageDefinition OUT, the extracted dispatch advices.
Standard Business Document Header In (SDBH)
A Standard Business Document Header (SDBH) is the effective message sent to a PEPPOL Access Point.
It's the UBL message wrapped in an envelop that identifies key data about the document.
Standard Business Document Header Out (SDBH)
A Standard Business Document Header (SDBH) is the effective message sent to a PEPPOL Access Point.
It's the UBL message wrapped in an envelop that identifies key data about the document.
Message Level Response (MLR)
A Message Level Response (MLR) is a business acknowledgment that tells the sender if the received message follows business rules related to the document type and business flow.
Message Delivery Notification of Message Level Response
A Message Delivery Notification (MDN) of a Message Level Response (MLR) is a proof from the receiver
that the MLR was correctly submitted to its destination.
RosettaNet Message Out
The content that was sent by Babelway to the RosettaNet server.
RosettaNet Receipt Out
The RosettaNet delivery report that was received from the receiver of the message, to prove that Babelway
has correctly submitted the message to its destination.
RosettaNet Message In
The content that was received by Babelway from the RosettaNet server.
RosettaNet Receipt In
The RosettaNet delivery report that was sent to the caller, to prove that Babelway has received the message.
X400 delivery report
The X400 message delivery report that was sent to the caller, to prove that Babelway has received the message.
SOAP Response
The soap response received in case of a SOAP gateway OUT.
NemHandel Message Out
The content that was sent by Babelway to the NemHandel server.
NemHandel Response Out
The NemHandel rasp response that was received from the receiver of the message, to prove that Babelway
has correctly submitted the message to its destination.
NemHandel Message In
The content that was received by Babelway from the NemHandel server.
19
Monitoring
NemHandel Response In
The NemHandel delivery report that was sent to the caller, to prove that Babelway has received the message.
Click on Back action to return to List of Messages screen.
Click on Resubmit to reprocess this message. See Resubmitting a Message chapter for more details.
Click on Save As Test Case to create a test case with the data of this message. The new test case is automatically created in the channel that processed the message and populated with the message parameters, including
the incoming message that will be used as a test message and outgoing message that will be used as expected
message out.
Changes done in release of November 2015
• The status Waiting ack has been merged to In progress, because the delivery of the message is not complete.
Example: Waiting for the file being downloaded by the client.
• A message may no longer stay forever in the status In progress. The message processing can only be ended
in statuses Success or Error. When applicable, it means that a timeout will terminate the message (for example if a file is not downloaded on a FTP server after X days).
• Dates and times associated with a message has been reviewed. The available date and times are now Message reception time, End processing time, End processing sla time and Keep until. See full description of all
fields of messages for full description of every field.
• Field Acknowledgment reference has been removed. This information is now available in the field Gateway
out message status
• All intermediate files generated during the processing are now saved and are downloadable. This is for example very useful to debug your messages when you have many extra processings (wrappers or unwrappers,
replacements based on regular expressions, ...), as you will now have access to the result after each step.
20
Monitoring
Figure 3.3. Message details new features screen
3.1.3. Resubmitting a Message
This function enables you to easily process a message again. This is especially useful when messages have not
been processed due to a channel issue. Once this issue is solved, go to the list of message, select the messages
that have not been processed and submit them again directly to the messaging engine.
It is also very useful when the issue is due to the message itself. You can just correct the input file, upload it
and resubmit the processing.
You can access this screen from the message details screen, or from the alert details screen.
21
Monitoring
Figure 3.4. Resubmit message screen
The Message in allows you to view or change the file that will be processed.
The Send to allows you to specify which channel or gateway must process the message
• Same channel: the message will be processed by the channel that processed the original message. The name
of the channel is displayed under brackets. This option could not be available if the channel that processed
the message doesn't exist anymore.
• Channel: the message will be processed by the specific channel you select. This can be for example very useful if the error in the processing is due to the message having been processed by a wrong channel (see routing
rules).
• Same gateway in: the message will be injected in the system as if it was received by the same gateway as the
original channel. This option could not be available if the gateway that received the message doesn't exist
anymore.
• Gateway in: the message will be injected in the system as if it was received by the gateway that you select.
Within the advanced options, you can edit metadata associated with the message. These metadata are typically
set by the gateway that received the message, and can be used during the process.
Once all parameters are setup up according to your preferences, click on the Send command to effectively
launch the reprocessing. You will be immediately redirected to the screen that shows the details of the reprocessed message.
3.1.4. Resubmit multiple messages
The resubmit all function allows you to resubmit many messages in one operation.
You can find this operation at the bottom of the messages list screen. Once you have selected all the messages
that you want to reprocess, just click on it. The test messages will be automatically excluded from the selection.
Figure 3.5. Selecting multiple messages for resubmit
22
Monitoring
The function works the same way as the resubmit message function. The difference is that you process here
many messages.
Figure 3.6. Resubmit multiple messages screen
The messages field show you the number of messages that you selected, and that will be reprocessed if you
continue. If this number is not correct, please click on back and change your search.
The send to field allows you to specify which channel or gateway must process the messages, and works exactly as for resubmit message.
Once all parameters are correct, click on Resubmit to launch the resubmission of all the messages. You will be
redirected to a screen that shows you the status of the resubmit, and allows you to stop the resubmit if you
want. You must stay on this screen until the end of the resubmit so that the resubmit can go to the end. Leaving
this screen is equivalent to click on Stop.
Figure 3.7. Resubmit multiple messages in progress
3.1.5. Download messages as a zip file
The download function allows you to download messages as a zip file.
You can find this operation at the bottom of the messages list screen. Once you have selected all the messages
that you want to download, just click on it. The test messages will be automatically excluded from the selection.
23
Monitoring
Figure 3.8. Selecting multiple messages for download
A message will inform you that a zip file will be created and that you will receive an email with instructions to
download it.
Figure 3.9. Resulting Message
The email you will received will look as follows:
Figure 3.10. Email sample
The zip file will contain received and generated files related to messages and a "messageRecords.csv" file that
24
Monitoring
contain the list of downloaded messages.
Figure 3.11. Zip file content
Some limits are implemented:
• Only one download is possible at a time.
• Your zip files will be deleted after 7 days.
• You can request a download of 1000 messages maximum. If you need to download more messages, don't
hesitate to contact the support team.
• If the resulting zip file is bigger than 200MB, the email will not contain a link to the zip file but you will be
asked to contact the support team to find a better way to obtain your file.
3.1.6. Verify a message integrity
Babelway keeps a secure chain of all messages, allowing to prove that a given message went through Babelway
at a given time and is unaltered.
Each message that goes through a channel is hashed (using SHA-512) and added to the "secure chain".
It's called a chain because when we add a message, we also hash a string that is composed of the current message and information from the previous message.
It is called secure because when we hash each new entry using information from the previous message, we
make it impossible to modify an entry of the chain without having to alter all the hashes that have been computed after that message has been added to the chain
In order to make sure that the chain is never modified, Babelway Team, regularly (several times a week) signs
25
Monitoring
and timestamp an element of the chain. The signature is done using Belgium electronic identity card (eID) that
uses another guarantee located in the offices of the Belgian government. The timestamp is done using an external public TSA (Timestamp Authority).
This guarantees that Babelway is able to prove that a message was processed by our system, even if the message is not stored anymore in Babelway archive (only the hash and the detached signature are kept). This gives
you all the guaranties of confidentiality, Babelway does not keep messages if you don't want to, as well as guarantee of origin, integrity and timestamping for all messages processed in each account.
You can access the digest of the message, and see when it was signed and certified, by clicking on the lock
after the message files in the message details screen.
Figure 3.12. Signature info
If someone receives a message from Babelway or from an email that looks like a Babelway email and would
like to verify that it was indeed processed by given Babelway account (i.e. it is not a fake), he can ask our support team
3.2. Alerts
An alert is a signal sent by the Babelway system to inform you that something abnormal has happened. For example,the most common type of alert is to inform you when the processing of a message failed.
All alerts should normally be handled by a human. Once the problem is solved, the alert should be deleted (or at
least closed).
You'll be warned in the Welcome Page if you have open alerts.
26
Monitoring
3.2.1. Alerts list
The list of alerts allows you to browse and search all the alerts generated by the Babelway systems.
To access this screen, just click on the Monitoring menu item, then on Alerts sub-menu item.
Figure 3.13. List of alerts
The detailed explanation of each possible column can be found in alert details.
Click on a line to access all the details about the alert, and be able to make actions on it.
3.2.2. Alert details
The alert details displays all the information about an alert, and allows you to take the necessary actions to
solve the problem.
27
Monitoring
Figure 3.14. Detail of an alert
Severity
The seriousness of the issue, it can be High, Medium, Low or Info.
Status
The alert status, it can be either Open or Closed. It is important to close the alerts once the problem is resolved, as the system will remind you if you have open alerts pending.
Type
The type of alert, see Possible Alerts for a complete list and further information.
Created On
The alert generation date and time.
Summary
A short description of the issue.
Description
An additional description of the issue.
Key
An uuid that uniquely identifies the alert within the Babelway platform.
Comments
Enable you to add comments about the issue. It may be useful to keep track of actions already taken to
solve the problem.
Related messages
When applicable, gives you a direct link to the message(s) that caused the problem.
Related channels
When applicable, gives you a direct link to the channel(s) related to the problem.
Attachments
Enable you to download attachments available from the system. For example: The negative acknowledgment from AS2 gateway.
You can click Close when the problem described in the alert is solved, or on Reopen if a previously closed alert
was not correctly solved.
You can click Delete when the problem described in the alert is solved, and you don't want to see it anymore in
your alerts list.
The action Resubmit linked message is a shortcut to easily resubmit the message linked to the ticket.
3.2.3. All possible alerts types
This page describes all possible alert types. The types should also be grouped from a logocal way.
Note
Explanations to be completed.
28
Monitoring
General monitoring
...
Message Processing Issue
...
Unidentified Source
...
Unidentified Message In
...
Unidentified Channel
...
Message Validation Issue
...
Failed Delivery
...
Planned Deletion of Unattended Messages
...
Hub Issue
...
Storage Capacity Reached
...
Planned Maintenance Unavailability
...
New Functionality Available
...
Account Issue
...
Credit Limit Reached
...
Outstanding Invoice
...
Credit Limit Almost Reached
...
VAT Rate Has Changed
...
Channel Management Issue
...
Notification ot a Change in a Linked Channel
29
Monitoring
...
Planned Deletion of Unused Channels
...
Documentation of a Channel
...
User Management Issue
...
Failed Connection Attempts
...
First Connection of new New User
...
Planned Deletion of Inactive Users
...
Invitation Expired
...
3.3. Statistics
The Statistics section allows you to view some aggregated data about your environment and your messages.
This data can be displayed in graphics or in table.
3.3.1. Status statistics
This screen allows you to have some aggregated view about the messages processed by your system.
You can select the period of time for which you want to see the stats, and if you want that the data is aggregated
by channel, gateway in or gateway out.
The resulting graphic will display one horizontal bar for each aggregated element (channel, gateway in or gateway out). This bar will be split following the status of the messages. The total count will also be displayed.
30
Monitoring
Figure 3.15. Status by channel
In the graphic, you can click on the legend to hide or show some status. This is very useful to clearly see the
few errors (if occurred) amongst the many Success messages.
Figure 3.16. Status by channel, Success messages are hidden.
31
Monitoring
You can also click directly on the bars in the graph to go to the messages lists screen, with the correct search
criteria filled, to see these messages exactly.
The refresh action button allows you to refresh the data.
The Switch to data action button allows you to switch to the grid display of the number. It can be especially
useful if you have many channels, and want to see all of the data (graphic is limited to 40 elements), or if you
want to export the data.
Figure 3.17. Messages stats
3.3.2. Time evolution statistics
This screen allows you to see the evolution of the messages processed over time.
These statistics count all messages that went through the system, even if the message has now been deleted.
Within the options, you can select the data that you want to see on the graphics: counts of messages, sizes of
messages or both.
You can also select the granularity of the graphics. Aggregate data by one month means that there will be one
point or one bar on the graphic by month.
You can also select to display the graphic in lines or in bars. Please note the following points:
• Graphics in lines are zoomable. You can drag with your mouse on the graphic over the wanted period.
Double-click anywhere on the graph to return to the full view.
• If you display both message counts and messages sizes, this option will only apply to messages counts. Messages sizes will always be displayed in line.
32
Monitoring
Figure 3.18. Count and sizes of messages by month.
33
Monitoring
Figure 3.19. Zoom in line graphic.
3.3.3. Traffic shape statistics
This graphic shows you the graphic shape over one day, or over one week.
The Type of graphic option allows you to choose between:
• Traffic shape over one day: To see the repartition of your messages amongst the 24 hours of the day. First
data point will count the messages in the selected period that you receive between 0am and 1am, second
point between 1am and 2 am, ...
• Traffic shape over one week: To see the repartition of your messages amongst the one week. Messages will
also be counted by hour : successive point will be for counts of messages for Monday 0am to Monday 1am,
Monday 1am to Monday 2am, ... till Sunday 11pm to Sunday 12pm.
The second option allows you to choose which messages will be counted: Messages for the last 1 week, 4
weeks, 1 month, ... Please note that only the messages that are currently visible in your interface will be counted, and not message that have been deleted.
34
Monitoring
Figure 3.20. Traffic shape over one week
35
Monitoring
Figure 3.21. Traffic shape over one day
3.4. Documents
Documents allows you to have a business view on the processed messages.
For example, you can have here the list of your invoices, with fields like Amount, Currency, DueDate, Recipient, ...
You can fully configure the type of documents that you want to use, and all the fields that you want to have.
This can be done in the admin section.
Figure 3.22. Example of document list : invoices.
To have documents displayed here, you must first :
• Configure your DocumentTypes in the admin section (which DocumentType do you want? With which
fields? ...)
• Extract business infos of your messages, by using ExtraProcessing "Extract documents" on your MessageDefinitions.
36
4
Channels
This section of the application contains all that is needed to configure how the messages should be processed by
the Babelway system.
The different sub-menu items contain the different building blocks available to make it work.
4.1. Overview
This section gives you the high-level view of how the messages are processed by the Babelway systems.
In Babelway words, the messages are processed by Channels. A channel defines all the path that a message follows within Babelway, from the external system that generated the input file, to the external system that must
receive the output.
Its main components are:
• The gateway in specifies the way incoming messages are communicated from the source external system to
Babelway. Babelway supports a large variety of protocols, including FTP, AS2, HTTP, Email, OFTP, SFTP,
X400 or web upload.
• The message in precisely describes the structure of the incoming message.
• The transformation tells Babelway how the incoming message should be translated to the outgoing message.
• The message out precisely describes the structure of the outgoing message.
• The gateway out specifies how the outgoing message should be communicated to the target external system.
Some optional components are:
• The test cases are a great way to be sure that your channels are correctly configured, and produce the expected results.
• The notifications allow you to receive emails when messages are processed, or are in error.
• The routing allows you to define which channel must process a message, when multiple channels use the
same gateway in.
Another important concept is the concept of deployment: when you are setting up your channels, you can make
any changes you want without any risk to the production system. You can work safely without impacting your
production flow of messages, until you're satisfied with the new setup, and want the changes to take effect for
the production messages. At this time, you have to deploy your environment, so that the new setup is migrated
to the servers that handle your production messages.
.
37
Channels
4.1.1. Channels list
The List of Channels screen shows you all the channels defined in your environment, and is the starting point
for editing them, create new ones or deploy them to the production systems.
Figure 4.1. Channels list screen
The list can contain the following columns:
Name
A name that identifies the channel.
Description
A free description for the channel.
Created on
The date and time when the channel was created.
Last updated on
The date and time of the last modification that affected the channel.
Status
Indicates if the channel is now running in the production system (value top bar ), or not (value Off ). See
deployment for more details.
Next deployment
Indicates which kind of change will be applied to the production systems at next deployment. Possible values are No change (channel will not be impacted by next deployment), Start (channel is currently not deployed, but will be after next deployment), Stop (channel is currently deployed, but will be undeployed at
next deployment) or Apply changes (channel is currently activated and modifications will be applied at deployment). See deployment for more details.
Enabled
Indicates if the channel is Enabled or Disabled. See deployment for more details.
Gateway In
38
Channels
The name of the gateway In used in this channel, or blank if it is not yet defined.
Message In
The name of the message In used in this channel, or blank if it is not yet defined.
Transformation
The name of the transformation used in this channel, or blank if it is not yet defined.
Message Out
The name of the message Out used in this channel, or blank if it is not yet defined.
Gateway Out
The name of the gateway Out used in this channel, or blank if it is not yet defined.
Id
A technical identifier that uniquely identifies the channel.
You can click on a line to view the details of the associated channel, or edit it. See Channel details.
The Create channel action button allows you to create new channels.
The Deploy action button allows you to deploy your environment.
4.1.2. Creation of a new Channel
This screen allows you to create a new channel from scratch.
It is accessible from the channels list screen.
The screen will just prompt you for a name and a description for your channel. When filled, just click on Create
channel. The channel will then be created, and you will be redirected to the channel detail screen, so that you
can edit all of its components.
Figure 4.2. Create a channel
The other method to create a channel is to search for an existing channel in the Reuse and save time zone.
4.1.3. Channel detail
All the information required to configure a channel is displayed here, split into different tabs. Tabs are presen39
Channels
ted in a logical order starting with the gateway for the incoming message, going to message transformation,
gateway for the outgoing message, email notifications, routing rules, and finally testing.
Figure 4.3. Channel detail screen
General
This tab displays the following information. You can change it by just editing the fields and click on Save.
Name
The name of the channel.
Description
The description of the channel.
Enabled?
A channel can be disabled to be ignored by future deployments. A disabled channel is just as a deleted
channel, except that you can keep it for future use. An enabled channel is just a 'normal' channel, and all its
changes will be reflected to the production system at every deployment.
Next deployment
Tells what will happen with this channel at next deployment. 'Apply Changes' means that the channel is
already in production but has changed since the last deployment; the changes will be deployed. 'Start'
means the channel is not yet in production, but will be after next deployment. 'Stop' means the channel is
currently in production, but will be removed at next deployment. 'No change' means nothing will be done
about this channel at next deployment.
Message storage duration
How long the message processed by this channel will be kept. This value can also be set at environment
level.
It also displays information about date and times where the channel was created or last updated.
The Delete action allows you to delete your channel.
40
Channels
The Duplicate action allows you to duplicate your channel.
In the top right corner, there is important information: The status of the channel and the deploy action.
Figure 4.4. Channel status and deploy action
You will find more information in the deployment section.
Gateway In
The gateway In specifies the way incoming messages are communicated from the sources external system to
Babelway. Babelway supports a large variety of protocols, including FTP, AS2, HTTP, Email, OFTP, SFTP,
X400 or web upload.
You can find all information about how to define and configure gateways in the gateways chapter.
Message In
The message In precisely describes the structure of the incoming message.
You can find all information about how to define and configure message definitions in the message definitions
chapter.
Transformation
The transformation tells Babelway how the incoming message should be translated to the outgoing message.
You can find all information about how to define and configure transformations, including the behavior of the
visual drag-and-drop editor, in the transformations chapter.
Message Out
The message Out precisely describes the structure of the outgoing message.
You can find all information about how to define and configure message definitions in the message definitions
chapter.
Gateway Out
The gateway Out specifies how the outgoing message should be communicated to the target external system.
You can find all information about how to define and configure gateways in the gateways chapter.
Email Notifications
For each individual channel, you may configure automatic notifications that send emails to specified addresses
upon arrival of new messages. Notified users can be different if the message has been successfully processed or
if an error has been generated.
41
Channels
You can find all information about how to define and configure notifications in the notifications chapter.
Routing
The routing allows you to define which channel must process a message, when multiple channels use the same
gateway In.
You can find all information about how to define and configure gateways in the routing chapter.
Testing
The test cases are a great way to be sure that your channels are correctly configured, and produce the expected
results.
You can find all information about how to define and configure gateways in the test cases chapter.
Related Items
Figure 4.5. Related Items
The following tabs give you quick links to many other elements of the application that are related to this channel :
Parent channel
Channel used as base for this channel.
Children channels
Channels based on this channel
Other channels with same gateway IN
Displays the channels using the current channel's gateway In
Other channels with same message definition IN
Displays the channels using the current channel's message In
Other channels with same message definition OUT
Displays the channels using the current channel's message Out
Other channels with same gateway OUT
Displays the channels using the current channel's gateway Out
42
Channels
Previous channels (within this environment)
Channel from which the current channel receive messages.
Following channels (within this environment)
Channels following the current channel to execute advance functions.
Messages processed by this channel
Redirect you to the messages list containing only the messages of this channel.
4.1.4. Deployment
When you are setting up your channels, you're working in a sandbox that is separate from the production systems, so that you can make any changes or tests you want without any risk to the production system and your
production flow of messages.
When you are satisfied with the changes , and want the changes to take effect for the production messages, you
have to deploy your environment. Only at this time, the new setup is migrated to the servers that handle your
production messages.
Please also note that the deployment always affects your whole environment. It is not possible do deploy
changes of only one channel.
Keep also in mind that any server, mail address, etc. defined in incoming and outgoing gateways are only created during deployment. A new incoming email address for example will not be available and any mail sent to
that address will generate an error before deployment.
You can access the deployment screen from the list of channels or from the detail of a channel. In the top right
corner, there is information about the deployment status of your channel
Figure 4.6. Channel status and deploy action
Status
The status tells if a channel is currently deployed in production ( On ) or not ( Off ).
Deploy action
By clicking on it, you will open the deployment screen. A tooltip will inform you about which kind of
change will be applied to the production systems at next deployment.
• to start the channel: channel is currently not deployed, but will be after next deployment.
• to apply the changes you made: channel is currently activated and modifications will be applied at deployment.
• to stop the channel: channel is currently deployed, but will be undeployed at next deployment.
If the deploy action is disabled, a tooltip will describe the reason :
• because no changes have been made to this channel
43
Channels
• because the channel is disabled: You can enabled it in the General tab (See the channel detail ).
• because it contains errors: Follow the exclamations marks to see where errors are.
Before the deployment takes effect, a summary of the things that will be changed on your production system
will be displayed. The changes are displayed in a grid, one affected channel by line. For all the channels, the 3
last fields describe the changes:
Figure 4.7. Deployment confirmation
On this screen, the following two advanced functions are also available:
Run tests
When deploying, the system automatically reruns all test cases of the affected channels, and forbids the deployment if some test cases are in error. The goal of this operation is to guarantee that you don't deploy by
accident a channel that is not functional. If you are really sure of what you are doing, you can decide not to
run the tests. In very large environments, this can result in big performance improvement, but at the cost of
being sure that the channels pass the tests.
Full provisioning
The system performs by default incremental provisioning: only the changed channels and configurations
are resent to the production system. This option allows to completely undeploy and redeploy your environment.
4.1.5. Delete a Channel
To delete a channel, just click on Delete in the general tab of the channel detail screen.
This action is not available if the channel is currently deployed. If it is the case and you want to delete it, you
must first undeploy it from the production systems (click on Disable, then Deploy).
A confirmation screen will be shown.
By default, only the channel will be deleted, not the elements (gateways, message definitions, transformations,
...) that the channel could reference. But it is possible to also delete the elements, thanks to the advanced options in the confirmation screen. Just click on the elements that you also want to delete. Note also that this list
44
Channels
only includes elements that are deletable, that means that are not referenced by other channels or transformations.
Figure 4.8. Delete a channel
4.1.6. Duplicate a Channel
This operation allows you to easily create a channel similar to an existing one.
By default, the created channel will be completely independent from the source one : all referenced elements
(gateways, message definitions and transformations) will also be duplicated. But you can change this in the advanced options, by specifying element by element, if you want to make a copy, share the existing element, use
another similar element or even leave it empty.
Figure 4.9. Duplicating a channel
45
Channels
The duplication can be accessed from the general tab of the channel detail screen, or from the create channel
screen. You have to use this second location if you want to use as source channel a channel from a different environment than the current one.
4.2. Gateways
This section contains all the tools needed to manage your gateways. A simplified edition of the gateways is directly available in the channels overview, but you need to come to this section to have access to all functionalities.
Gateways are used in Babelway to specify how messages are communicated between external systems and the
Babelway system.
Each channel contains 2 gateways:
• Gateway in is used to specify the way incoming messages are communicated from the source external system
to Babelway.
• Gateway out is used to specify the way outgoing messages are communicated from Babelway to the target
external system.
Babelway supports a large variety of protocols, including AS2, FTP, OFTP, Email, Http. To browse the full
list of available gateways, see our catalogue, or consult the different gateway types.
4.2.1. Gateways list
The List of Gateways screen shows you all the gateways defined in your environment, even if they have not
been used in any channel. From here, you can easily edit them, or create new ones.
This screen is accessible by clicking on the menu Channels, then the sub-menu Gateways
Figure 4.10. List of gateways
46
Channels
Name
Description
Direction
IN for gateways in, or OUT for gateways out.
Type
The type of the gateway. See gateway types for all possible values.
Created on
Last updated on
For more information about the behavior of the grid, and how to make searches, see the grid section for help.
You can click on a line to view the details of the associated gateway, or edit it. See gateway details.
The Create gateway action button allows you to create new gateways.
The Clean gateways action button allows you to very easily delete all the gateways that are not used. The interface will just show you the list of all gateways that are deletable (this mean not used in any channel). You'll just
have to tick the ones that you want to be deleted, and confirm the operation.
Figure 4.11. Clean gateways
4.2.2. Creation of a gateway
To create a gateway, you have two main options:
• Create the gateway from scratch.
• Duplicate an existing gateway that you already created, or from the Babelway catalogue.
You can access this choice by clicking on Create a gateway in the gateways list screen, or directly from the
channel detail screen.
Create a new gateway.
47
Channels
To create a gateway, first you have to select the type of gateway that you want to use (Email, FTP, AS2, HTTP,
...).
Figure 4.12. Gateway creation - Type choice.
Then you need to fill the parameters of the gateway and click on Create gateway. The parameters depend on the
type of gateway selected. You can find a detailed explanation of every gateway type in the section on GatewayTypes..
Figure 4.13. Gateway creation - Parameters for Email
48
Channels
Figure 4.14. Gateway creation - Parameters for FtpClient
After having clicked on Create gateway, you will receive a confirmation that the gateway is correctly created,
or a detailed error message if your parameters are not correct.
Figure 4.15. Gateway creation - Confirmation
Figure 4.16. Gateway creation - Error
Reuse an existing gateway.
The other solution is to select an existing gateway from the "Reuse and save time" zone.
49
Channels
Figure 4.17. Gateway creation - Reuse
Figure 4.18. Gateway creation - Reuse confirmation
When you are in the Channels section, and you reuse a gateway that is already used in other channels, you will
have the choice of either to share the gateway, or to make a copy.
Figure 4.19. Gateway creation - Share or copy
More details can be found in the Reuse and save time section.
4.2.3. Gateway detail
This page shows all the details about a gateway, and gives access to all operations that can be made on gateways.
This page can be accessed from the gateways list, or by following any link that refers to a gateway.
The page contains the following tabs.
General
The general tab contains the signaletic information of the gateway, and offers actions that act on the whole
gateway.
Direction
Field used to indicate if the message is coming in the system or leaving it.
Type
50
Channels
Type of the gateway. See gateway types for more details.
Name
A name that you can set and/or modify to easily retrieve and manage your element.
Description
A free text field that you can set and/or modify used in addition to element name to help you identify your
element usage and/or function.
Id
A unique identifier automatically set by Babelway platform.
Created On
Date and time of element creation.
Last Updated On
Date and time of last element configuration update.
If the gateway is based on time, for instance a FTP Client Gateway using polling, this page contains a Poll now
action button. This button triggers the gateway action directly without waiting for the next defined moment.
Properties
This tab contains the configuration of the gateway.
The parameters depend on the type of the gateway.
Related items
This tab contains quick links to many other elements related to this gateway.
Using channels
All the channels that use this element.
Parent
The parent is the element from which the element has been copied.
Children
The children is the element which is a copy of the current element.
Connected gateways (within this environment)
List of gateways to which this gateway sends messages.
Connected gateways (within this environment)
List of gateways from which this gateway receives messages.
Connected Notifications
List of notification from which this gateway receives messages.
Messages processed by this gateway
A link that shows you the message list filtered, to show messages processed by this gateway.
Connected Message Definition (through extra-processing)
List of message definition that have an extra-processing related to this gateway.
51
Channels
Change Log
This tabs shows you all the history of changes made on this gateway, and allows you to revert to a past version.
For more details, see the change log section.
4.2.4. Gateway types
Here is the list of all the gateway types used in the application, with some more information about their specific
uses and parameters.
Gateway In
• Email Gateway: Incoming messages are attached to email messages and sent to a specific Babelway email
address and processed as soon as they arrive.
• FTP Client Gateway: Incoming messages are polled and retrieved from a remote ftp server using a login and
password.
• SFTP Client Gateway: Incoming messages are polled and retrieved from a remote sftp server using a login
and password.
• FTP Server Gateway: Incoming messages are transferred to a specific Babelway Ftp server and processed as
soon as they arrive.
• SFTP Server Gateway: Incoming messages are transferred to a specific Babelway sftp server and processed
as soon as they arrive.
• AS2 Gateway: A communication standard largely used in retail environment to secure communications over
the Internet.
• Internal Gateway: A gateway used to transfer messages between 2 channels within Babelway.
• Lookup table Gateway: used to create a message using values present in a lookup table.
• OFTP Server Gateway: Incoming messages are transferred to a Babelway specific OFTP server and processed as soon as they arrive.
• OFTP Client Gateway: Incoming messages are polled and retrieved from a remote OFTP server using login
and password.
• Http Client Gateway: Incoming messages are polled and retrieved from a remote Http server.
• Web Scraping Gateway: Incoming messages are polled using a scenario mimicking a browser navigating the
web.
• Http Gateway: Incoming messages are transferred to a Babelway specific Http server and processed as soon
as they arrive.
• Rest Gateway: Allows you to implement a REST api.
• X.400 Gateway: Incoming messages are transferred to a Babelway specific X.400 server and processed as
soon as they arrive.
• Scheduler Gateway: Create new messages based on time triggers.
52
Channels
• NFS Gateway: Incoming messages are polled and retrieved from a remote NFS server using login and password.
• SAP Gateway In: Incoming messages are pushed to Babelway from a SAP server and processed as soon as
they arrive.
• Dropbox Gateway: Incoming messages are polled from a Dropbox account.
• Certione Gateway: Incoming messages are polled from a Certione account.
• Tradeshift Gateway: Incoming messages are polled from a Tradeshift account.
• E-conomic Gateway In: Incoming messages are pushed to Babelway from an E-conomic account and processed as soon as they arrive.
• VAN Gateway In: Incoming messages are polled from ECGrid VAN.
• PEPPOL Gateway In: Incoming messages are received from the PEPPOL network.
• RosettaNet Gateway In: Incoming messages are received from a RosettaNet server.
• ePrior Gateway In: Incoming messages are received from ePrior requests.
• Amazon Marketplace Gateway In: Incoming messages are polled from an Amazon marketplace account.
• NemHandel Gateway In: Incoming messages are received from the NemHandel network.
Gateway Out
• Email Gateway Out: With an Email Gateway Out, outgoing messages are attached to an email and sent to a
specific email address.
• FTP Client Gateway: With a Ftp Client Out Gateway, outgoing messages are transferred to an external Ftp
server.
• SFTP Client Gateway: With a SFTP Client Out Gateway, outgoing messages are transferred to an external
SFTP server.
• FTP Server Gateway:With a Ftp Server Out Gateway, outgoing messages are available from a Babelway
FTP server.
• SFTP Server Gateway:With a Sftp Server Out Gateway, outgoing messages are available from a Babelway
SFTP server.
• AS2 Gateway: A communication standard largely used in retail environment to secure communications over
the Internet.
• Internal Gateway: The internal gateways in / out are used to transfer messages between 2 channels inside the
same Babelway environment.
• Null Gateway: The outgoing messages are not sent anywhere.
• Splitter Gateway: A gateway used to split your messages and pass them to other gateways.
• Aggregator Gateway Out: The aggregator allows you to merge messages into one larger file. The resulting
messages are forwarded to another channel in the same environment.
53
Channels
• Lookup table Gateway: used to fill a lookup table automatically from a message.
• OFTP server Gateway: With an OFTP Server Out Gateway, outgoing messages are available from a Babelway OFTP server.
• OFTP Client Gateway: With an OFTP Client Out Gateway, outgoing messages are transferred to an external
OFTP server.
• HTTP out Gateway: With a HTTP out Gateway, outgoing messages are available from a Babelway HTTP
server.
• Http Client Out Gateway: With an Http Client Out Gateway, outgoing messages are send using a Http connection.
• Soap Client Out Gateway: With an Soap Client Out Gateway, outgoing messages are sent using a SOAP call.
• ePrior Soap Client Out Gateway: With ePrior Soap Client Out Gateway, outgoing messages are sent using a
SOAP call to Belgian ePrior/Mercurius platform.
• ePrior Out Gateway: With ePrior Out Gateway, outgoing messages are made available on Babelway ePrior
server.
• X.400 Gateway Out: With a X.400 Gateway, outgoing messages are sent to a specific trading partner address
using a X.400 network.
• NFS Gateway: Outgoing messages are pushed from Babelway to a NFS server.
• SAP Gateway Out: Outgoing messages are pushed from Babelway to a SAP server.
• Dropbox Gateway: Outgoing messages are pushed from Babelway to a Dropbox account.
• Exact Postbox Gateway: Outgoing messages are pushed from Babelway to an Exact POSTBOX account.
• Tradeshift Gateway: Outgoing messages are pushed from Babelway to a Tradeshift account.
• Billtrust Gateway: Outgoing messages are pushed from Babelway to a Billtrust API.
• VAN Gateway Out: Outgoing messages are pushed from Babelway to ECGrid VAN.
• PEPPOL Gateway Out: Outgoing messages are sent to the PEPPOL network.
• RosettaNet Gateway Out: Outgoing messages are sent to a RosettaNet server.
• Amazon Marketplace Gateway: Outgoing messages are sent to Amazon marketplace account.
• NemHandel Gateway Out: Outgoing messages are sent to the NemHandel network.
Email Gateway In
Email gateway in allows you to receive incoming messages sent to a specific Babelway email address, as attachments. The messages are processed as soon as they arrive.
The specific parameters are:
Email address
The email address to which the incoming messages are sent as email attachment.If the address already ex54
Channels
ists, you will have to enter a new address. Remember that this email address will only be created at channel
deployment.
Ftp Client Gateway In
With a Ftp Client In Gateway, incoming messages are transferred from an external Ftp server. Babelway polls
files from this server at regular intervals.
Server
External ftp server address where Babelway should fetch messages, eg. ftp.example.com
Username
Login or username to access files on this external ftp server.
Password
Password associated to the username.
Passive Mode
Indicates that the ftp connection is in passive. Ticking this means the ftp client will establish 2 connections
to the ftpserver client.
Directory
Directory where files are to be fetched on the server.
File pattern
The file pattern is a regex used to filter files to import (ex: '.*\.csv' for all file ending with '.csv' or
'(?!proc_).*\.csv' for all csv file that don't start with 'proc_'. If left empty, all files will be transferred.
Protocol
Select FTP, FTPS (Explicit mode) or FTPS (Implicit mode) protocol.
Private key
The private key associated with the previous username to access your account. This can be left empty if
you choose to only use the password authentication mechanism.
Suffix during transfer
Suffix that will be appended to the file name when a file is being transferred. This mechanism is used to
prevent that a file is transferred twice.
After transfer behaviour
What will happen to your file after we have read it. This behaviour is important so that your file is not read
again at next poll. The possible values are :
• Delete. It is the default. After having read it, the file will be deleted from the remote server.
• Rename. A suffix will be appended to the file name.
• Move. File will be moved to another folder of the remote server.
• Move and rename. File will be moved to another folder, and renamed.
• DoNothing. Don't do anything. Be very careful with this option, as it could mean that your file will be redownloaded at each poll. Should only be used with servers that move or delete the file automatically at
55
Channels
download.
Suffix after transfer
Suffix that will be appended to the file name when a file has been completely transferred.
Folder for transferred files
Directory where transferred files will be moved.
Cron expression
Cron expression. Allows you to define complex time expression like every weekday night at 23:00 (0 23 ?
* MON-FRI). If left empty, the system will check at least once every 15 minutes. For easy creation of your
cron expression, you can use the online cron maker tool available at http://www.cronmaker.com/. For more
information, please refer to the page: http://www.quartz-scheduler.org/docs/tutorials/crontrigger.html
When a message is transferred to the ftp server, it is processed immediately then the original file is removed
from the server.
Ftp Server Gateway In
With a Ftp Server In Gateway, incoming messages are received on a Babelway specific ftp server and processed as soon as they arrive.
Server
Babelway ftp server set as "ftp.babelway.net"
Username
Login or username to access your account on Babelway ftp server. This username must be unique as it is
linked to a specific directory on the ftp server.
Password
Password associated with the username.
Directory
The directory on the ftp server on which you wil have to put your files so that they are processed by this
gateway.
After channel deployment, your ftp server will be available to send messages. You can access this ftp server using any ftp client software set up with the previous account parameters.
Babelway FTP gateways are supporting FTP and FTPS (Explicit mode) on port 21. It also support FTPS
(Implicit mode) on port 990.
SFTP Client Gateway In
With a SFTP Client Input Gateway, incoming messages are transferred to an external SFTP server. Babelway
platform polls this server at regular intervals and retrieves incoming files to process them.
Server
Sftp server host name
56
Channels
Username
Login or username to access files on this external sftp server.
Password
Private key
Private key associated with the username.
Directory
Directory where files are to be fetched on the server.
File pattern
The file pattern is a regex used to filter files to import (ex: '.*\.csv' for all file ending with '.csv' or
'(?!proc_).*\.csv' for all csv file that don't start with 'proc_'. If left empty, all files will be transferred.
Cron expression
Cron expression. Allows to define complex time expression like every weekday night at 23:00 (0 23 ? *
MON-FRI). If left empty, the system will check at least once every 15 minutes. For easy creation of your
download.
Suffix that will be appended to the file name when a file has been completely transferred.
SFTP Server Gateway In
Using the SFTP Server In Gateway,incoming messages are received on a Babelway specific server and processed as soon as they arrive. The SFTP server gateway supports SFTP version 3 and password and/or public
key user authentication mechanisms.
57
Channels
Server
Babelway SFTP server default value is 'sftp.babelway.net'.
Username
Login or username to access your account on the Babelway SFTP server. This username must be unique as
it is linked to a specific directory on the SFTP server.
Password
The password associated with the username. This can be left empty if you choose to only use the public key
authentication mechanism.
Public Key
The public key associated with the username. This can be left empty if you choose to only use the password
authentication mechanism. The supported formats are RSA public key (OpenSSH, Putty or DER format).
More information about generating such a key can be found at the end of this page.
Directory
The directory on the ftp server on which you wil have to put your files so that they are processed by this
gateway.
You can set both password and public key fields. Therefore, you will be able to connect to your account either
by using a password or by using your private key associated with the uploaded public key.
After channel deployment, your SFTP server will be available to send messages. You can access this SFTP
server using any SFTP (version 3) client software set up with the previous account parameters.
When a message is received by the SFTP server, it is directly processed. After processing the file is removed
from the server
The public key is expected to be in a RSA format (OpenSSH, Putty or DER). If you don’t already have a public/private key, you can generate one using ssh-keygen from OpenSSH :
C:\cygwin\bin>ssh-keygen.exe
Generating public/private rsa key pair.
Enter file in which to save the key (/.ssh/id_rsa): /tmp/identity
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /tmp/identity.
Your public key has been saved in /tmp/identity.pub.
The key fingerprint is:
f0:e4:2f:(...) user@computer
AS2 Gateway
With an AS2 Gateway, incoming messages are received using an AS2 connection. Incoming files are processed
as soon as they are received.
AS2 (Applicability Statement 2) is a specification about how to transport data securely and reliably over the
Internet. Security is achieved by using digital certificates and encryption.
From
AS2 ID of the server that sends incoming messages. Provided by your partner
58
Channels
To
AS2 ID of the Babelway destination server. You must communicate it to your partner
Local URL address
URL address used by your partner to send messages to this gateway. It works for both http and https protocol.
AS2 documentation
File containing instructions and certificates for the installation. You should download it and send it to your
AS2 partner.
Message signature enforced
Should message signature be enforced or not.
Certificate for verification
Certificate used for message verification. Provided by your partner.
Message encryption enforced
Should message encryption be enforced or not.
Certificate for decryption
Local certificate to use for decrypting the AS2 messages. These certificates are kept in the environment certificates store.
Maximum retries
Maximum number of retries if message sending failed. Default is 8 times.
Retry interval
Interval of time before trying to send message again (in seconds). Default is 1800 (30 minutes).
After channel deployment, your AS2 connection will be available to receive messages.
To report AS2 parameters to the other party, dowload the AS2 documentation ZIP file. This file can send to the
other party to give them all parameters they will require to establish a communication with your channel.
OFTP Server Gateway In
With an Oftp server Gateway in, Incoming messages are received on a Babelway specific OFTP server and processed as soon as they arrive.
Partner SSID
Partner SFID
The SFID provided by your partner. If none has been provided, this is probably the same as SSID.
Partner password
The password of your partner. Provided by your partner.
My SSID
Babelway is providing an official Odette SSID : O01770000000000X0B5SHARED. Please call support if
you want to use a different one.
My SFID
59
Channels
An SFID is automatically assigned to your Environment: O01770000000000X0B5xxxxxx. Please call support if you want to use a different one.
My password
The value of the password is 'BABELWAY'.
OFTP documentation
OFTP partner.
Use compression
Compresses the messages.
Sign messages
Sign outgoing messages using the key selected in "Signature certificate". This allows your partner to verify
that you are the one sending the message. This option is only available with OFTP 2.0.
Signature certificate
Select signature certificate or go to certificates store. This option is only available with OFTP 2.0.
Encrypt messages
Encrypt outgoing messages using the certificate selected in "Encryption certificate". This allows your partner to be the only one able to decrypt the messages sent. This option is only available with OFTP 2.0.
Encryption certificate
Select encryption certificate or go to certificates store.
Encryption algorithm
Select encryption algorithm or go to certificates store.
Receive signed messages
This allows you to verify that your partner is the one sending the message using the certificate selected in
"Signature verification certificate". This option is only available with OFTP 2.0.
Signature verification certificate
Select certificate for data or go to certificates store.
Request signed ack (EERP)
Requests that incoming acknowledgments are signed. The signature will be verified using the Certificate
selected in "EERP verification certificate". This allows you to be sure that only the partner could have
signed the incoming messages. This option is only available with OFTP 2.0.
EERP verification certificate
Select certificate for EERP or go to certificates store.
Transfer mode
Advanced. Once the connection is open the OFTP gateway will act as both sender and receiver by default.
You can control this by setting the following values : BOTH / RECEIVER_ONLY / SENDER_ONLY
Version
Advanced. Babelway is supporting both OFTP1 and OFTP2. When a connection is open, Babelway uses
the OFTP built-in mechanism to negotiate the protocol version. The protocol will be the highest possible.
Valid values are : OFTP_V12 for version 1.2 / OFTP_V13 for version 1.3 / OFTP_V14 for version 1.4 /
OFTP_V20 for version 2.0
Credit count
60
Channels
Advanced. Control the OFTP "creditCount" parameter. This is the number of data command ( = CREDIT)
that could be exchanged prior to an OFTP confirmation from the partner. Default is 64
Data exchange buffer size
Advanced. Control the OFTP "dataExchangeBufferSize" parameter. This is the size of the OFTP data buffer. It should be smaller than the maxBDataLen for ISDN connection. The minimum is 128 bytes and the
maximum is 4096 for ISDN and 65535 for TCP connections. Default is 1024
Server configuration
Local server configuration. Leave empty for the shared Babelway OFTP. Contact support for special needs.
After channel deployment, your Oftp server will be available to send messages. You can access this oftp server
using any Oftp client software set up with the previous account parameters.
If you require a custom SSID / SFID / PASSWORD, please send a request to [email protected] .
When a message is transferred to the Oftp server, it is processed immediately then the original file is removed
from the server.
OFTP client Gateway In
With an OFTP Client In Gateway, incoming messages are transferred from an external OFTP server. The Babelway platform polls this server at regular intervals and retrieves files to process them.
Partner SSID
The OFTP ID provided by your partner.
Partner SFID
The SFID provided by your partner. If none has been provided, this is probably the same as the SSID.
Partner password
My SSID
My SFID
An SFID is automatically assigned to your Environment: O01770000000000X0B5xxxxxx. Please call support if you want to use a different one.
My password
OFTP documentation
OFTP partner.
ISDN number
List of phone numbers used for ISDN communication instead of Internet communication. The expected
format is a comma separated list of phone numbers ex : 0049511211306466 or
0049511211306466,003221234567
61
Channels
Max nb datablocks
Advanced. Control the OFTP "maxBDataBlocks" parameter (ISDN only). Default is 7
Max size datablock
Advanced. Control the OFTP "maxBDataLen" parameter (ISDN only). Default is 1024
Server
The URL of the server of your partner. It is provided by your partner.
Port
The port to connect onto. It is provided by your partner.
Use TLS
Use TLS (SSL) for communication
Secure Authentication Certificate
Use this certificate to perform client side TLS (SSL) authentication.
Cron expression
Use compression
Secure Authentication
Use OFTP2 'Secure Authentication'. This will use the certificates defined for encryption and signature.
Sign messages
Encrypt messages
62
Channels
Transfer mode
Advanced. Once the connection is open, the OFTP gateway will act as both sender and receiver by default.
Version
Advanced. Babelway supports both OFTP1 and OFTP2. When a connection is open, Babelway uses the
OFTP built-in mechanism to negotiate the protocol version. The protocol will be the highest possible. Valid
values are : OFTP_V12 for version 1.2 / OFTP_V13 for version 1.3 / OFTP_V14 for version 1.4 / OFTP_V20 for version 2.0
Credit count
Local server configuration. Use 1 for the shared Babelway OFTP. Contact support for special needs.
from the server.
Http In Gateway
With an Http In Gateway, incoming messages are received as HTTP Post on the Babelway HTTP server and
processed as soon as they arrive.
The HTTP Post can use the following encoding method: HTML Form, base64 and urlencode.
Babelway is supporting synchronous processing of messaging. This is available when you submit messages using our HTTP gateway using SOAP and the SOAP operation: "process Message". The response will contains
the final result of the execution of the messages. If the messages generates more than one messages, the response will contains the full graph of processed messages.
It is also available through the REST of the gateways. There is only a limited available documentation on this
topic, but we would be more than happy to understand more your requirements and provide a proof of concepts
for you.
63
Channels
Username
Login or username to access the service.
Password
Password associated with previous username.
HTTP Post URL
Using the HTTP Post protocols.
SOAP Url
Using the SOAP Post protocols. WSDL1
Submitted using a FORM
Check the message posting was performed using a Http POST submit.
FORM parameter
If the option "Submitted using a FORM" is used, this selects the parameter where to find the content of the
message.
Http In Client
The Http Client allows to periodically retrieve the content of the Http response to a specific URL
Url
Url to call to create message.
Username
Username used for BASIC authentication.
Password
Password used for BASIC authentication.
Http headers
You can add specific http header.
Valid HTTP return code
Comma separated list of expected return Http code. If the return code is not in the list, the polling generates
an alert. The default is '200,201,202,204,205'.
Cron expression
Web Scraping
The Web scraping allows to periodically retrieve messages using a scenario mimicking a browser navigating
the web.
Scenario
1
https://ws.babelway.net/ws/SoapIn?WSDL
64
Channels
Xml definition of the web scraping scenario.
See the complete documentation of the scenario syntax.
Use variables from lookup table
The scenario will be executed once per iteration ookup table row block. The value of the lookup table will
added to the execusion context and available using the VARIABLE::columnName function. Scenario will
be executed once without parameters if lookup table is left empty.
Cron expression
Rest In Gateway
This gateway in allows you to easily publish a REST api.
It has the following characteristics:
• It will respond synchronously to the REST api calls with the result of the processing of the message by the
channels.
• It injects a xml message in that contains all the elements of the REST call (uri, parameters, expected output
format, ...).
• It supports 'json', 'xml' and 'csv' as output format.
• It supports multi-credentials.
Url identifier
Part of the url that identifies this gateway. The urls to call the REST api will have the form https://ws.babelway.net/rest/<urlIdentifier>/<yourUrlParams>.(json|xml|csv)
Allowed credentials.
A list of user names/passwords pairs that are allowed to access this api. The user will have the choice to
provide user name and password via http basic authentication, http parameters 'user' and 'password' or http
headers 'user' and 'password'.
Url patterns
Optional. If filled, the requested url will be checked again. This pattern will be refused it it doesn't match at
least one pattern. You can also prefix the pattern with 'PRE:', 'POST:', 'PUT:', ... if you want this pattern to
only be accessible via one specific http method.
Here is an example of message In, that is generated by this gateway.
<?xml version="1.0" encoding="UTF-8"?>
<restRequest>
<uri>/sws/shipmentStatus/BE.json</uri>
<identifier>sws</identifier>
<action>shipmentStatus</action>
<method>GET</method>
<format>json</format>
65
Channels
<userName>bertrand</userName>
<parameters>
<param1>BE</param1>
<myParam>myValue</youpie>
</parameters>
</restRequest>
X.400 Gateway In
With a X.400 In Gateway, allows receival of message from X.400 networks. Your trading partners can reach
you via your private X.400 address.
X.400 address
The account private address. This is the address to communicate to your trading partners. The formatting
may vary from one partner to the other. The most common format is: C=WW; A=400NET;
P=BABELWAY; S=HUB-25333 /C=WW/A=400NET/P=BABELWAY/S=HUB-25333.
After channel deployment, your connection will be available to send messages.
The first time X.400 is used in an account, it has to be enabled by Babelway support. The request is done automatically and you will be notified when the gateway is functional.
Scheduler in Gateway
The Scheduler in Gateway allows you to create a message based on a time trigger.
Frequency
Number of seconds between two events. The default value is 90 seconds and cannot be lower. This is the
simplest way to define a time event. For more complex need, use the Cron Expression property instead.
Cron expression
MON-FRI). This takes precedence on the frequency property. For easy creation of your cron expression,
you can use the online cron maker tool available at: http://www.cronmaker.com/. For more information,
please refer to the following page: http://www.quartz-scheduler.org/docs/tutorials/crontrigger.html
Message
Message template that will be sent each time this scheduler is activated. If not filled, a default xml is used
(that just contains the time and the gateway id).
Internal Gateway In
The internal gateway in / out are used to transfer messages between 2 channels within the same account environment.
There is no parameter to define in this template. The internal gateway will be automatically created using the
gateway name you entered. You will then be able to select it as an Internal Gateway Out in another channel
configuration.
66
Channels
As opposed to most other gateways, the internal gateway is immediately available as the gateway out for other
channels configuration without requiring a channel deployment.
Lookup table Gateway In
This gateway allows you to create a message from the content of a lookup table. The message created is a XML
document. It uses the same format as the XML CVS representation used internally by Babelway.
Lookup Table Id
The technical id of the lookup table.
Include headers
Check this to add the column names as headers of the messages created.
Filter 1 column
Column used to filter the extract of the lookup tables entries.
Filter 1 value
Value used to filter the extract of the lookup tables entries.
Filter 2 column
Filter 2 value
Filter 3 column
Filter 3 value
Post extract operation
Optional operation to perform on selected entries after extraction. Default is DELETE
Column to update
Column to update after the extract of the lookup tables entries, Only used with 'Update' in 'Post extract operation'.
Column to update
Column to update after the extract of the lookup tables entries, Only used with 'Update' in 'Post extract operation'.
Update value
Value to use when updating the column to update.
Limit
Maximum number of entries to extract in 1 execution of this gateway.
Entries per message
Maximum number of entries per message. If the overall limit is bigger, several messages will be created for
each execution of this gateway.
Cron expression
67
Channels
* MON-FRI). If left empty, the system will check at least once every 15 minutes. For easy creation of your
cron expression, you can use the online cron maker tool available at: http://www.cronmaker.com/. For
more
information,
please
refer
to
the
following
page:
http://www.quartz-scheduler.org/docs/tutorials/crontrigger.html
NFS Gateway
The NFS gateway is used to connect and fetch files from a remote NFS server.
Server
Hostname of the NFS server.
Export
Name of the exported volume.
Login method
NFS login method: use PCNFSD for username / password and UGID to directly use UID, GID and GIDS.
Username
Username used for the NFS authentication. Only used with PCNFSD login method.
Password
Password used for the NFS authentication. Only used with PCNFSD login method.
User ud
Unix user UID to use during authentication. Only used with UGID login method.
User group id
Unix user's group GID to use during authentication. Only used with UGID login method.
User extra group ids
Unix user's additional groups GID to use during authentication, encoded as a comma separated list. Only
used with UGID login method.
Directory
Local NFS path to the folder you want to use. This is relative to the export.
Filename pattern
If not empty, only the files whose name matches this pattern will be transferred.
68
Channels
download.
Suffix that will be appended to the file name when a file has been completely transferred. The use of this
mechanism allows you to keep the file after the transfer, with this suffix appended to its name. If left
empty, the file will be deleted after the transfer.
Cron expression
By default, the gateway will regularly poll the messages from your NFS server, so that they come into Babelway a short time (less than 10 minutes) after they have been placed in your NFS server. You can write
here a cron expression to customise the polling schedule. For easy creation of your cron expression, you
can use the online cron maker tool available at : http://www.cronmaker.com/.
SAP Gateway In
The SAP Gateways are based on the SAP RFC protocol and JCo technology. RFC is an SAP interface protocol
allowing internal or external systems to communicate with the SAP system. JCo is the Java implementation of
RFC distributed by SAP. Babelway leverage the built-in JCo redundancy mechanism to distribute the gateway
on our different locations (data centers).
Figure 4.20. Solution overview
System boundaries, acknowledgment and error management
For Inbound IDoc, Babelway sends the IDoc to SAP. If the message cannot be delivered to SAP, the error will
be managed using the traditional Babelway process. Error notifications will be delivered to registered users.
When the message is delivered to SAP, Babelway fetches the detailed status and error messages of the IDoc.
The messages are always set to 'acknowledged' when the transmission is successfully. However the status could
be SUCCESS or ERROR depending the SAP IDOC status code.
For Outbound IDoc, SAP sends IDOC to Babelway. If the message cannot be delivered to Babelway, the IDoc
69
Channels
is in error in SAP with a status = 20. Once the message is delivered to Babelway, SAP automatically change the
status to 03. In addition of this, we provide a function to explicitly change the status by calling the RFC defined
during the setup phase. This allow SAP that the remaining of the IDoc processing will entirely take place in Babelway.
Connectivity Setup
Babelway provides the gateways to communicate in both direction. SAP Gateway In allows to receive outbound IDoc and SAP Gateway Out allows to send inbound IDoc to SAP. The JCo RFC Provider service uses a
TCP/IP connection type. In order to secure this connection, Babelway advices one of the following solutions:
• Option 1: A strict firewall rule to allow 4 Babelway public IP addresses to connect to the SAP server
• Option 2: Using SAP router in the DMZ, as well as the firewall configuration like in Option1
• Option 3: You can contact Babelway support to setup a IPSec VPN between the 4 Babelway public IP addresses and the SAP server. Please send a request to [email protected]
The Port number used to contact the SAP system range from 3300 to 3399. The exact port number depends on
the SAP system you want to reach. The exact port number must be given in the parameters (defined below).
Firewall need to allow Babelway server to reach these ports.
SAP configuration
Here is the list of the SAP specific setup to perform in order to make the connector working. This is guide lines
• Create a "RFC destination" (transaction sm59) with the name "BABELWAY". The "Connection Type" is
"TCP/IP Connection". Go to "Technical settings" and fill "BABELWAY" in the "Program ID" field. Go next
to the "Unicode" tab and in the "Communication Type", select the "Unicode".
70
Channels
Figure 4.21. RFC destination
• Create a "Ports in IDoc processing" (transaction we21) in the "Transactional RFC" with the name "BABELWAY".
71
Channels
Figure 4.22. Ports in IDoc processing
• For inbound IDoc, there is no special configuration. All programs are allowed to delivered IDocs for all partners. For outbound IDoc, Go to "Partner profiles" (transaction we20) then for each partner and each "Message Type" you want to change, go to "Outbound Options" and change the "Receiver port" to "BABELWAY" in the tab "tRFC".
72
Channels
Figure 4.23. Sap Partner Profiles
73
Channels
Figure 4.24. Sap Partner Profiles Outbound Parameters
• If you want to leverage the "Update Status" feature, you need to add the specific RFC call. By default the
system will call the following function: ZZBABELWAY_IDOC_STATUS_UPD taking 2 input parameters:
PI_DOCNUM (IDoc number) and PI_STATUS (the new status = 16). The code for such function is given
here2.
• Here is a list of transactions that could help you during the setup of your connection:
• sm59 : maintenance of "RFC destination"
• we21 : maintenance of "Ports in IDoc processing"
• we20 : maintenance of "Partner profiles"
• we02 : "IDoc List"
• we19 : "Test tool for IDoc processing"
2
http://www.babelway.com/help/resources/sap_updateStatusBapi.txt
74
Channels
• sm58 : "Transactional RFC". Use this to look for TID = Gateway In message key
• smgw : "Gateway Monitor"
• sm21 : "System Log"
• we63 : "Documentation" usefull to get IDoc parser or XSD to use in Babelway wizard
• su01 : "User Maintenance"
Babelway configuration
Simply create a channel with the SAP gateway and XML IDoc message definition.
Figure 4.25. Sap Channel Details
The specific parameters are :
SAP client
SAP client to use. This is the three digit number you use in the first field of the login screen of SAP Gui. It
has the name 'Client' and is just above the user and password fields. For instance: 001, 210, 400 ...
User
The Valid SAP user ID you want to use. Ideally this should be a user specially created for this purpose. For
instance: user
Password
75
Channels
Password associated with the user ID. For instance: password
Server address
IP or DNS name for SAP application server. For instance: sap.yourcompany.com if using a sap router, use
the sap router syntax details here: /H/SAP_ROUTER/S/3300/H/SAP_SERVER/S/3300 http://help.sap.com/saphelp_nw04/helpdata/en/4f/993172446d11d189700000e8322d00/frameset.htm if you
are using a NAT: put the public address in sm59
RFC destination
This is the name of the RFC Destination to use. This RFC destination must use TCP/IP connection. See
help for more details. For instance: BABELWAY
SAP system number
SAP system number is the last 2 digits of the SAP client. For instance: 01, 10, 00. Default is the last 2 digits of SAP client parameter
Gateway address
IP or DNS name for SAP gateway. It could be the same as jco.client.ashost if no external gateway is used.
the For instance: gateway.yourcompany.com. Default is the same as SAP server address parameter.
Gateway port
This is the port number to reach the TCP RFC server. For instance use 3301 to reach system 01 or 3310 to
reach system 10. Default is 3300 + the last 2 digits of SAP client parameter.
Custom update status
Should the system call the RFC function to explicitly update the status in SAP. Default is true and it required a RFC to be configured in SAP. Default is false.
Update status function
The name of the RFC updating the status. For instance: ZZBABELWAY_IDOC_STATUS_UPD
Use unicode
Specify if unicode should be used. Use 0 for false and 1 for true. For instance: 0
Dropbox Gateway In
The Dropbox gateway in allows to retrieve your messages from a Dropbox account.
Dropbox account
The name of the Dropbox account from which the messages are polled. This information is "read only",
and set by the wizard when you allow Babelway to access the Dropbox account.
Folder
The folder in your Dropbox account from which the messages are transferred to Babelway. This folder is
located under the path /Applications/Babelway/ .
Filename pattern
If not empty, only the files whose name matches this pattern will be transferred to Babelway. Otherwise, all
files are automatically transferred to Babelway
76
Channels
download.
Suffix that will be appended to the file name when a file has been completely transferred. The use of this
mechanism allows you to keep the file after the transfer, with this suffix appended to its name. If left
empty, the file will be deleted after the transfer.
Scheduling
By default, the gateway will regularly poll the messages from your Dropbox account, so that they come into Babelway a short time (less than 10 minutes) after they have been placed in your Dropbox account. You
can write here a cron expression to customise the polling schedule. For easy creation of your cron expression, you can use the online cron maker tool available at : http://www.cronmaker.com/.
Tradeshift In Gateway
This gateway allows to retrieve files directly from an account on Tradeshift. The document retrieved will be
marked as 'processed-by-babelway' in Tradeshift. The message will contain 2 metadata, 'document.metadata'
containing the document metadatas and 'connection.properties' containing the connection properties, both as a
single line JSON string.
API URL
URL Prefix to call Tradeshift API. Default is https://api.tradeshift.com/tradeshift/rest/
Polling type
Choose 'Document' for regular fetching of document. Choose 'Workflow' to poll workflow document.
Tenant Id
The Tradeshift tenantId to use. Use Babelway application in Tradeshift to retrieve this value.
Token
The Tradeshift token to use. Use Babelway application in Tradeshift to retrieve this value.
Secret
The Tradeshift token secret to use. Use Babelway application in Tradeshift to retrieve this value.
Consumer key
The Tradeshift consumer key to use to authenticate the Babelway application. This should be left empty in
77
Channels
most of the case.
Consumer secret
The Tradeshift consumer secret to use to authenticate the Babelway application. This should be left empty
in most of the case.
Stag
Specify where the document should be retrieved from. Values are 'inbox', 'outbox', 'sales', 'purchases', 'inbox,outbox', 'inbox,outboxsales,purchases', 'draft', 'sent'. Default is 'inbox'.
Type
type of document to retrieve. Values are 'invoice', 'creditnote', 'order', 'despatchadvice', 'invoice,creditnote',
'invoice,creditnote,order,despatchadvice'. Default is 'invoice'.
Additional query parameters
Parameter list added to the initial 'list documents' api call.
Frequency
Number of seconds between 2 checks. The default value is 3600 seconds (1 hour) and it can be lowered;
the minimum accepted value is 90 seconds. This is the simplest way to define a time event. For more complex need, use the Cron Expression property instead.
Cron expression
By default, the gateway will regularly poll the messages from your Tradeshift account, so that they come
into Babelway less than one hour after they have been placed in your Tradeshift account. You can write
here a cron expression to customise the polling schedule. For easy creation of your cron expression, you
can use the online cron maker tool available at : http://www.cronmaker.com/.
Amazon Marketplace In Gateway
This gateway allows to retrieve orders from an account on Amazon Marketplace. The gateway will only process orders created after the deployment of the gateway.
Process
Request [email protected] for changing this parameter. Type of process. 'PollOrders' is the only one
supported at this stage.
Endpoint
Endpoint is the entry point
tps://mws.amazonservices.com
for
an
Amazon
marketplace
web
service.
Default
is
ht-
Access key
Amazon marketplace web services access key ID.
Secret key
Amazon marketplace web services secret key ID.
Seller Id
Amazon marketplace seller ID.
Marketplace Id
Amazon marketplace ID.
Cron expression
By default, the gateway will regularly poll the messages from your Amazon Marketplace account, so that
78
Channels
they come into Babelway less than one hour after they have been placed in your Amazon Marketplace account. You can write here a cron expression to customise the polling schedule. For easy creation of your
cron expression, you can use the online cron maker tool available at : http://www.cronmaker.com/.
E-conomic Gateway In
The E-conomic wizard is used to create a gateway that lets you query your e-conomic online account
(http://www.e-conomic.com) and retrieve invoice documents based on a specified CVR reference.
E-conomic Token Id
The generated Token Id by E-conomic that grants Babelway access to your E-conomic account.
It
can
be
generated
via
https://secure.e-conomic.com/secure/api1/requestaccess.aspx?appId=N3m3TyMMqNgwTTso7dnr7f3rGOnX
lZwKEeneiL2Uwo0=&role=SuperUser.
CVR Reference
Reference to Central Business Register (CVR). Only invoice documents with this reference will be retrieved by Babelway.
Cron expression
cron expression, you can use the online cron maker tool available at : http://www.cronmaker.com/. For
more
information,
please
refer
to
the
following
page:
http://www.quartz-scheduler.org/docs/tutorials/crontrigger.html.
VAN In Gateway
This gateway allows to retrieve files from specific trading partners on ECGrid VAN. A Trading Partner is the
company from whom you are going to receive documents.
The VAN gateway receives the message based on the Identifier / Qualifier pair as determined in the X12 or
Edifact data. They look like this:
X12: ISA*00* *00* *ZZ*SENDERID *ZZ*RECEIVERID *010101*0101*U*00401*000000001*0*T*!
EDIFACT: UNB+UNOA:1+ SENDERID:ZZ+RECEIVERID:ZZ +
For the VAN IN Gateway, your ID Is the Receiver ID. Your Trading Partner ID is the Sender ID.
If you are using an already existing ID (on another VAN), your ID must be migrated to Babelway before you
can begin receiving documents. To do so you must:
Download and complete this letter of authorization, found here 3
Printout on your company letterhead, scan with completed information
Send authorization to <[email protected]> along with your desired migration date
Please note that this migration will cause all traffic under this ID to be routed to the Babelway VAN Gateway
3
http://www.babelway.com/authorization-letter-template-ec-grid-van/
79
Channels
In. You must be prepared to process all documents that you currently receive through your old VAN before the
migration can be completed successfully.
Your identifiers
Your Names / Identifiers / Qualifiers on VANs. All EDI messages specifying these Id/Qual in recipient will
be routed to this gateway. Identifier = The X12 or EDIFACT ID for the ISA and UNB segments. Qualifier
= The X12 or EDIFACT Qualifier for the ISA and UNB segments (Maximum is 2 characters). The name
should be your company/ entity name and will be used by other EDI partners to find you before sending
messages.
PEPPOL In Gateway
This gateway allows to receive files from the PEPPOL network.
PEPPOL ?
The PEPPOL project was started in 2008 with the objective to enable businesses to communicate electronically
with any European government institution in the procurement process. Seven years later, PEPPOL standard is
gaining traction by the European governments but also within the industry (the peppol.eu4 site lists 99 certified
PEPPOL Access Points providers).
The three main components of the PEPPOL architecture are :
• The Access Point (AP) : responsible to send and receive documents for a PEPPOL participant
• The Service Metadata Publisher (SMP) : registry containing the Participant AP information. It tells you
which access point must be contacted to send document of certain type to a PEPPOL participant
• The Service Metadata Locator (SML) : the PEPPOL directory (a DNS Server). It tells you in which SMP a
PEPPOL participant is registered
4
http://www.peppol.eu
80
Channels
Figure 4.26. PEPPOL In Gateway
Participant
An "PEPPOL In Gateway" must be configured for one PEPPOL Participant (the receiver). There can be only
one PEPPOL Gateway IN per participant identifier in Babelway.
The identifier value is the value identifying the PEPPOL participant in a given identification scheme. Most of
the time this is a national VAT or a GLN number. For easier use, you can, for each identifier, define a userfriendly name that we call a "label".
When you deploy an "PEPPOL In Gateway", the gateway is registered as an Access Point for the receiver and
document types in a Babelway SMP and the Babelway SMP is referenced in the SML for this participant.
The participant SML status tells you if the participant is registered in the PEPPOL SML.
Figure 4.27. PEPPOL In Gateway - Participant SML status
Some actions are available depending on the participant status :
• Prepare migration : Let you start the participant migration to another SMP than Babelway. It will generate a
migration key that need to be exchange with the new SMP.
81
Channels
• Migrate : If the participant is registered to another SMP in the SML, this action lets you migrate him to a Babelway SMP. The migration key received from the old SMP need to be entered.
• Register : If the participant is not registered at all in the SML, you can register it by clicking on this action.
Registered Documents
Registered documents are UBL document type that are customized and categorized by PEPPOL business flows
(i.e. : An UBL v2.1 Invoice that follows business specifications of the PEPPOL BIS 4a v2.0 ). One or more
document types can be choose to configure the gateway.
Figure 4.28. PEPPOL In Gateway - Document types
Message Level Response
A Message Level Response (MLR) can be sent back to the sender of the PEPPOL message. A MLR is a business acknowledgment that tells the sender if the received message follows business rules related to the document type and business flow. You can choose the "MLR strategy" in the Gateway IN configuration.
Here is the summary of gateway properties:
PEPPOL environment
Choose between the regular PEPPOL production infrastructure, connected to the SML, or the test infrastructure, connected to the SMK. The default is Production
Identifiers Values
The values identifying the PEPPOL participants.
List of documents accepted by this gateway and registered in the SMP.
Message Level Response
Using this option you can decide to send MLR directly after message reception. The options are :
• No MLR MLR will never be sent automatically. The MLR is completely under the responsibility of the
environment maintainer. This is the right choice if you want to generate a MLR based on the response of
a back-end system or if the partner is not supporting MRL.
82
Channels
• Error MLR only MLR is sent automatically if the incoming message is not conforming to the documents
customization business rules (schematron rules). In this case the MRL is return and the message is
marked as 'ERROR' in Babelway. With this strategy, the 'SUCCESS' business acknowledgement flow
can be based on the response of a back-end system.
• All MLR MLR will always be sent back. An negative MRL is sent if the message is not conforming to
the documents customization business rules (schematron rules), a positive MLR is sent otherwise.
Participant SML status
The status of the participant in the PEPPOL SML
RosettaNet In Gateway
This gateway allows to receive RosettaNet complient PIP message from an other RosettaNet Server. The resulting message is the body of the Service Content section of the MIME message. Signature and Encryption are
supported.
Url
URL of the RosettaNet server of the receiver.
Return receipt acknowledgment
Return the ReceiptAcknowledgment (RNIF v2.00) synchronously to the caller. If the option is not selected,
the content of a valid ReceiptAcknowledgment is placed in the metadata of the message with the name
'RosettaNetReceiptIn' to be used later by the processing.
Decryption certificate
Select signature certificate or go to certificates store.
ePrior In Gateway
This Gateway allows to receive messages through ePrior requests.
Signature Verification Certificate
The X509 certificate used to verify the signature of the incomming ePrior requests.
Document Type
The document type which is accepted by the ePrior gateway.
NemHandel In Gateway
This gateway allows you to receive messages from the Danish NemHandel network.
Registration certificate
Select the certificate use to register your information into the NemHandel registry.
NemHandel environment
Choose between the regular NemHandel production infrastructure, or the test infrastructure. The default is
83
Channels
Production
Identifiers Values
The values identifying the NemHandel participants.
List of documents accepted by this gateway.
Email Gateway Out
With an Email Gateway Out, outgoing messages are attached to an email and sent to a specific email address.
To Recipients
Email address to which messages will be sent (destination). You can add a comma separated list of recipients or a metadata.
Cc Recipients
Email destination CC address.You can add a comma separated list of recipients or a metadata.
Bcc Recipients
Email destination Bcc address.You can add a comma separated list of recipients or a metadata.
Sending Email Address
Email address from which messages will appear to be sent. Replies will be sent to that address.
Secure Email
If checked, the email message is signed using the transfer certificate. The sending email address should be
[email protected] where XXXXX is your account environment id.
Track email using web beacon
If checked, a web beacon (an image containing a unique link) will be in the footer of the email. When the
image is loaded for the first time, it will report it as an acknowledgement of the reception of the message.
Subject
Email message subject.
Body type
[text/plain , text/html] default is text/plain
Email body
Email message Body.
HTML codes < and > must be escaped.
See http://www.htmlescape.net/htmlescape_tool.html for an online tool.
Send message as attachment
Should the message be sent as attachment or not.
Attachment name
Attachment file name.
84
Channels
Send message as a link
Add a download link in the message body. When the link is first clicked, it will "acknowledge" the message.
Text of message link
This is the text displayed for the download link. Default: "download message".
Attachments
Allows you to attach other files to the email. Name = filename of the attachment. Value = Pattern to match
metadata containing the file to attach. If one pattern matches multiple files, it is possible to attach them all
if you guarantee to generate a different filename name for each. This can be achieved by using the capturing groups of the regex in the filename. Ex: if your metadata pattern is attachment-(.*) and your filename is
\1, processing with two metadata attachment-file1.csv and attachment-file2.csv will result in files file1.csv
and file2.csv.
Ftp Client Gateway Out
With a Ftp Client Out Gateway, outgoing messages are transferred to an external Ftp server.
The following fields should be defined in order to configure access to your external ftp server:
Server
External ftp server address where Babelway should send messages eg ftp.example.com.
Username
Login or username to access files on this external ftp server.
Password
Passive Mode
Indicates that the ftp connection is in passive. Ticking it means the ftp client will establish 2 connections to
the ftpserver client.
Retry strategy
Allows you to determine what to do if call to remote server fails. If 'No retry' is chosen, the message will be
put immediately in error. Other values allow to make some retries before setting the message in error.
Directory
Directory where outgoing files will be stored on the server.
Filename
Filename of the outgoing message.
Filename during transfer
Prefix and suffix that will be prepended and appended to the file name when a file is being transferred. This
mechanism is used to prevent that a file is read before it is complete. However some systems do not allow
to remotely rename files or directly process and delete the file triggering an ERROR in Babelway.
Protocol
Select FTP, FTPS (Explicit mode) or FTPS (Implicit mode) protocol.
Private Key
The private key associated with the username to access your account. This can be left empty if you choose
85
Channels
to only use the password authentication mechanism.
Ftp Server Gateway Out
With a Ftp Server Out Gateway, outgoing messages are available from a Babelway FTP server, where they can
be fetched.
Server
Babelway ftp server set as "ftp.babelway.net"
Username
Password
Password associated with the username to access your account.
Directory
The directory on the ftp server into which the outgoing files will be written.
Filename
Time out
During how much time the file will be kept available on the FTP server.
After this timeout, the file will be automatically removed from the FTP server (it you did not do it before).
If the file was never downloaded, the file will also be marked in ERROR, because it has not reached its
destination.
To be warned the soonest possible of errors, we recommend that you set here the lowest possible value. Example : if an automatic process polls the files from here every hour, a value of "3 hours" will allow you to
be notified of the problem after just 2 or 3 failed/missing pollings, while a value of "30 days" would lead to
files leaving there, without any automatic notification, until some user worries about lack of files.
After channel deployment, your ftp server will be available to receive messages. You can access this ftp server
using any ftp client software set up with the previous account parameters.
Sftp Server Gateway Out
With a Sftp Server Out Gateway, outgoing messages are available from a Babelway FTP server, where they can
be fetched.
Server
Babelway ftp server set by default as "sftp.babelway.net"
Username
86
Channels
Password
Password associated with the username to access your account.
Public Key
The public key associated with the username. This can be left empty if you choose to only use the password
authentication mechanism. The supported formats are RSA public key (OpenSSH, Putty or DER format).
More information about generating such a key can be found at the end of this page.
Retry strategy
Directory
The directory on the ftp server into which the ougoint files will be written.
Filename
Time out
During how much time the file will be kept available on the FTP server.
After this timeout, the file will be automatically removed from the FTP server (it you did not do it before).
If the file was never downloaded, the file will also be marked in ERROR, because it has not reached its
destination.
After channel deployment, your sftp server will be available to receive messages. You can access this sftp server using any sftp client software set up with the previous account parameters.
SFTP Client Gateway Out
With a SFTP Client Out Gateway, outgoing messages are transferred to an external SFTP server.
Server
External sftp server address where Babelway will send messages.
Username
Login or username to access files on this external sftp server.
Password
Password associated with the username to access account.
Private Key
The private key associated with the previous username to access your account. This can be left empty if
you choose to only use the password authentication mechanism. The supported formats are RSA private
key (OpenSSH format).
Directory
87
Channels
Directory where outgoing files will be stored on the server.
Filename
Filename during transfer
Prefix and suffix that will be prepended and appended to the file name when a file is being transferred. This
mechanism is used to prevent that a file is read before it is complete. However some systems do not allow
to remotely rename files or directly process and delete the file triggering an ERROR in Babelway.
OFTP client Gateway out
With an OFTP Client out Gateway, outgoing messages are transferred to an external OFTP server.
Partner SSID
Partner SFID
Partner password
My SSID
My SFID
An SFID is automatically assigned to your Environment : O01770000000000X0B5xxxxx where xxxxx is
the ID of your Babelway environment. Please call support if you want to use a different one.
My password
Filename
OFTP documentation
OFTP partner.
ISDN number
List of phone numbers used for ISDN communication instead of Internet communication. The expected
format is a comma separated list of phone numbers ex : 0049511211306466 or
0049511211306466,003221234567
Max nb datablocks
Advanced. Control the OFTP "maxBDataBlocks" parameter (ISDN only). Default is 7
Max size datablock
Advanced. Control the OFTP "maxBDataLen" parameter (ISDN only). Default is 1024
Server
88
Channels
The URL of the server of your partner. It is provided by your partner.
Port
The port to connect to. It is provided by your partner.
Use TLS
Use TLS (SSL) for communication
Secure Authentication Certificate
Use this certificate to perform client side TLS (SSL) authentication.
Skip EERP
Select this if your partner is not sending the mandatory EERP. The message will be set in SUCCESS directly after upload.
Use compression
Secure Authentication
Use OFTP2 'Secure Authentication'. This will use the certificates defined for encryption and signature.
Sign messages
Encrypt messages
Transfer mode
89
Channels
Version
Advanced. Babelway is supporting both OFTP1 and OFTP2. When a connection is open, Babelway is using the OFTP built-in mechanism to negotiate the protocol version. The protocol will be the highest possible. Valid values are : OFTP_V12 for version 1.2 / OFTP_V13 for version 1.3 / OFTP_V14 for version
1.4 / OFTP_V20 for version 2.0
File format
Advanced. Babelway is supporting all types of records. Valid values are : FIXED / TEXTFILE / UNSTRUCTURED / VARIABLE. Default is UNSTRUCTURED
Record max size
Advanced. You can specify the record size (only used for FIXED and VARIABLE)
Credit Count
from the server.
OFTP Server Gateway out
With an OFtp server Gateway out, outgoing messages are available from a Babelway OFTP server.
Partner SSID
Partner SFID
Partner password
My SSID
My SFID
An SFID is automatically assigned to your Environment : O01770000000000X0B5xxxxxx where xxxxx is
90
Channels
the ID of your Babelway environment.. Please call support if you want to use a different one.
My password
Filename
OFTP documentation
OFTP partner.
Skip EERP
Select this if your partner is not sending the mandatory EERP. The message will be set in SUCCESS directly after upload.
Use compression
Sign messages
Encrypt messages
Transfer mode
Version
91
Channels
Advanced. Babelway is supporting both OFTP1 and OFTP2. When a connection is open, Babelway is using the OFTP built-in mechanism to negotiate the protocol version. The protocol will be the highest possible. Valid values are : OFTP_V12 for version 1.2 / OFTP_V13 for version 1.3 / OFTP_V14 for version
1.4 / OFTP_V20 for version 2.0
File format
Advanced. Babelway is supporting all types of records. Valid values are : FIXED / TEXTFILE / UNSTRUCTURED / VARIABLE. Default is UNSTRUCTURED
Record max size
Advanced. You can specify the record size (only used for FIXED and VARIABLE)
Credit Count
from the server.
AS2 Gateway
With an AS2 Gateway, outgoing messages are transmitted using an AS2 connection.
AS2 (Applicability Statement 2) is a specification about how to transport data securely and reliably over the
Internet. Security is achieved by using digital certificates and encryption.
The following fields should be defined in order to configure your AS2 access:
From
Babelway source server.
To
AS2 ID of the server that receives outgoing messages. Provided by your partner.
type
MIME/TYPE used to transfer the AS2 message to your partner. Possible values are :
"edi", for the content type "application/EDIFACT".
"x12", for the content type "application/EDI-X12".
"eco", for the content type "application/edi-consent".
92
Channels
"xml", for the content type "application/XML".
"bin", for the content type "application/ octet-stream".
DEFAULT is "bin".
Attachment name
Name of the file sent by AS2. This is an extension to the base AS2 specification and might not be supported by all partners. By default no file name is sent.
Recipient address
The endpoint URL of the receiving gateway ,requires protocol prefix in URL (http:// or https://).
AS2 documentation
AS2 partner.
Compress message
Should the message be compressed or not?
Encrypt message
Should the message be encrypted or not?
Certificate for encryption
Certificate used for message encryption. Provided by your partner.
Select algorithm used for encrypting message, if any.
Sign message
Should the message be signed or not?
Certificate for signature
Local certificate to use for signing AS2 messages. The certificates are kept in the environment certificates
store.
Signing algorithm
Select algorithm used for signing the AS2 message. DEFAULT is SHA-1.
Request receipt
Should a receipt be sent when a request is received or not.
Asynchronous receipt
Should the receipt be sent asynchronously or not.
Signed receipt
Should the receipt be signed or not.
MIC algorithm
Select Message Integrity Code algorithm used to compute the MDN of the message. DEFAULT is SHA-1.
Message signature enforced
Should message signature be enforced or not. This parameter only applies if no AS2 IN gateway is configured for this parter (same AS2 FROM and AS2 TO).
Certificate for verification
93
Channels
Certificate used for message verification. Provided by your partner. This parameter only applies if no AS2
IN gateway is configured for this parter (same AS2 FROM and AS2 TO).
Maximum retries
Maximum number of retries if message sending failed. Default is 8 times.
Retry interval
Interval of time before trying to send message again (in seconds). Default is 1800 (30 minutes).
To report AS2 parameters to the other party, dowload the AS2 documentation ZIP file. This file can send to the
other party to give them all parameters they will require to establish a communication with your channel.
Http Client Out Gateway
With an HttpClientOut Gateway, outgoing messages are sent using a Http connection.
All the user defined metadatas defined in the messages are passed in the context of the new message.
Url
External service address.
Username
Password
Connected gateway
Select zero, one or several gateways to receive the response from the http server.
Comma separated list of expected return Http code. If the return code is not in the list, the message is set in
error. The default is '200,201,202,204,205'.
Success expression
The success expression is a regex. If the response doesn't match the success expression, the message is
flagged with 'error' status.
Response filename
You can specify a filename that will be associated with the server response. Default is 'attachment'.
User Metadata Transfer Strategy
The strategy that will be used to transfer the user metadata to the response message created in the connected gateways.
Retry strategy
Filename
Timeout
94
Channels
Timeout for connection in milliseconds. Must be between 10000 and 240000.
Http Method
You can specify the http method to call. 'Form Posting' is emulating a browser Form Post using mime multipart. The default is POST.
TLS version
You can specify the version of the TLS protocol. TLS is the replacement of SSL. The default is TLSv1.2.
Message parameter name
Name given to the parameter containing the actual message. This is also equivalent to the FORM parameter
when a POST if done from a web browser.
Extra parameters
Extra parameters to inlude in the message. Name is the parameter name (FORM parameter) and the value is
the name of a metadata containg the parameter content. In case of a binary content, the name of the
metadata will also be used as the 'filename' of the parameter.
Http headers
You can add specific http header. This accepts metadata.
Trust level
The trust level defines the level of security used in the SSL handshake. Relax = No certificate verification,
Standard = trusting certificates in environment certificates as well as known CA's, Paranoiac = only trusts
certificates defined in the environmnent certificates. Mutual = requires 2-way authentication.
Authentication method
You can select from FORM, BASIC, DIGEST, NTLM, CERT, OAUTH1, OAUTH2 or ANY. CERT is
2-way SSL authentication. ANY is BASIC, DIGEST or NTLM depending on the server response.
Preemptive authentication
Allows to send authentication information with the first http request (to avoid making a second request).
Only for BASIC or DIGEST authentication.
Login url
If authentication method is FORM.
Authentication form fields
When using FORM authentication, you can add specific authentication form fields to the authentication
call. This accepts metadata.
2-way auth. certificate
If CERT authentication is used (2-way SSL authentication), this allows to select the key pair to use from
the environment certificate.
Oauth bearer
If OAUTH2 authentication is used, this allows select the OAUTH bearer token to use.
Oauth signature method
If OAUTH1 authentication is used, this allows select the signature algorithm to use. Note that if
SHA1withRSA is used, a Key alias must be selected.
Oauth consumer key
If OAUTH1 authentication is used, this allows defined the consumer key. This is mandatory.
Oauth consumer secret
95
Channels
If OAUTH1 authentication is used, this allows defined the consumer secret. This is optional.
Oauth token
If OAUTH1 authentication is used, this allows defined the token. At this version of Babelway this is mandatory, please contact support if you need to retreive the token from an OAUth handsake.
Oauth token secret
If OAUTH1 authentication is used, this allows defined the token secret. This is optional.
Oauth RSA key
If OAUTH1 authentication is used with SHA1withRSA, this allows to select the key signing the OAUTH
authentication.
Soap Client Out Gateway
With an SoapClientOut Gateway, outgoing messages are sent using a SOAP call.
Url
Username
Password
Connected gateway
error. Note that the error 500 is accepted to allow the to push SOAP Fault to the next channel. The default
is '200,201,202,204,205,500'.
Success expression
Response filename
Retry strategy
96
Channels
Filename
Http Method
You can specify the http method to call. The default is POST.
Timeout
Http headers
SOAPAction http header
Value of the SOAPAction http header.
SOAP Attachments
Allows to specify one or more soap attachments, based on SOAP with Attachments (SwA) using MIME.
Name will be sent as 'ContentId' of the mime part of the attachment and Value must contain the name of the
metadata containing the String or byte array body of the attachment.
Trust level
Authentication method
You can select from FORM, BASIC, DIGEST, CERT or ANY. CERT is 2-way SSL authentication. ANY
is BASIC, DIGEST or NTLM depending on the server response.
Preemptive authentication
Allows to send authentication information with the first http request (to avoid making a second request).
Only for BASIC or DIGEST authentication.
Login url
If authentication method is FORM.
Authentication form fields
When using FORM authentication, you can add specific authentication form fields to the authentication
call. This accepts metadata.
2-way auth. certificate
If CERT authentication is used (2-way SSL authentication), this allows to select the key pair to use from
the environment certificate.
Soap headers
You can add specific soap header. This accepts metadata.
Soap version
Defined the standard version of the remote SOAP service.
Ws-Security profile
Ws-Security profile defines the type of security required to call the SOAP service.
Ws-Security Username
Ws-Security username is used in the username/token digest profile.
97
Channels
Ws-Security token
Ws-Security token is used in the username/token digest profile.
Ws-Security signing key
Ws-Security username is used in the X.509 signing profiles.
Ws-Security encryption certificate
Ws-Security username is used in the X.509 encryption profiles.
ePrior Soap Client Out Gateway
With ePrior Soap Client Out Gateway, outgoing messages are sent using a SOAP call to Belgian ePrior/
Mercurius platform.
ePrior Url
ePrior service address.
Connected gateway
Response filename
ePrior Out Gateway
With ePrior Out Gateway, outgoing messages are made available on Babelway ePrior server.
Signature Verification Certificate
The X509 certificate used to verify the signature of the incomming ePrior requests.
Consumer Identifier
The identification of the consumer from which the ePrior request comes from.
Receiver Identifier
The identification of the party to which the ePrior document is sent.
Sender Identifier
The identification of the party from which the ePrior document is sent.
Document Type
The type of the ePrior document.
Document Identifier
The identification of the ePrior document.
98
Channels
Time out
During how much time the file will be kept available on the ePrior server.
After this timeout, the file will be automatically removed from the ePrior server (it you did not do it before). If the file was never downloaded, the file will also be marked in ERROR, because it has not reached
its destination.
Http Out Gateway
With a HTTP out Gateway, outgoing messages are available from a Babelway HTTP server.
Username
Login or username to access the service .
Password
SOAP Url
using the SOAP Post protocol. WSDL5
HTTP Post URL
using the HTTP Post protocol.
Content encoding
How to encode the content
Time out
During how much time the file will be kept available on the HTTP server.
After this timeout, the file will be automatically removed from the HTTP server (it you did not do it before). If the file was never downloaded, the file will also be marked in ERROR, because it has not reached
its destination.
X.400 Gateway out
The X.400 out Gateway allows to send the message on the X.400 network to the address of your trading partner.
5
https://ws.babelway.net/ws/SoapOut?WSDL
99
Channels
X.400 Address
The account private address. This is the address to communicate to your trading partner. The formatting
may vary from one partner to the other. The most common formats are: C=WW; A=400NET;
P=BABELWAY; S=HUB-25333 /C=WW/A=400NET/P=BABELWAY/S=HUB-25333.
Partner Manual Address
You can choose to enter the full address in the "manual address field" or each address component in the
corresponding field.
Partner Country
Country = C value
Partner ADMD
Partner Administration Management Domain Name = A value
Partner PRMD
Partner Private Management Domain Name = P value
Partner Organization
Partner Organization = O value
Partner OU1
Partner Organizational Unit 1
Partner Given Name
Partner Given Name
Partner Initial
Partner Initial
Partner Surname
Partner Surname = S value
Partner Generation
Partner Generation Qualifier
Request receipt
Request a X.400 message delivery notification
Send as binary
Send the X.400 message as binary (using bilaterally-defined body part)
Internal Gateway Out
The internal gateway in / out are used to transfer messages between 2 channels within the same Babelway environment.
Connected Gateways
Select the internal gateways In that will receive the message. You can select multiple gateway in. A copy of
the message will be sent to each of them.
100
Channels
Filename
Response Filename
Filename of the Response message.
The strategy that will be used to transfer the user metadata to the new message created in the connected
gateways.
As opposed to most other gateways, the internal gateway is immediately available as gateway out for other
channels configuration without requiring a channel deployment.
Null Gateway
The null gateway can be used for test and development purposes. The outgoing message will not be sent anywhere and remain in Babelway.
Outgoing messages will not be forwarded but they are nevertheless created and readable through the Messages
interface. You may use this gateway for testing your messages before going to production or for preventing a
channel to send messages before deployment.
Filename
Splitter gateway out
The splitter gateway OUT enables to split a message into multiple messages. The splitter can split according to
RegEx, XPath, Edifact or X12 expressions. The resulting messages are forwarded to one or more channels in
the same environment.
Connected gateways
Select the internal gateways In that will receive the split messages. You can select multiple gateway in. A
copy of the message will be sent to each of them.
Split type
The split type determines how the file will be analyzed (text, xml, edifact) to split it in parts.
gateways.
Filename
Filename of the parent message.
Response filename
Filename of the split message.
Header expression
Regex expression to create a header added to each split message
101
Channels
Expression
XPath or RegEx expression to select the content of the split message.
[\n](?=EE)
which means split when seeing line return and then EE
Footer expression
Regex expression to create a footer added to each split message
Keep xml parents
Keep the parent node of the split xml. Only valid with XPath splitting.
Omit xml declaration
Skip the xml declaration in the split xml. Only valid with XPath splitting.
Xslt
Optional Xslt to perform on the split Xml. Only valid with XPath splitting.
Input charset
Charset to use to decode file waiting to be split.
Output charset
Charset to use to encode the file resulting of the splitting.
Aggregator Gateway Out
The aggregator gateway OUT enables to aggregate messages into one single file. The aggregator can append
the messages, use a xslt to merge xml documents or merge Edifact or X12 documents. The resulting message is
forwarded to one or more channels in the same environment.
All the user defined metadata defined in the first of the aggregated messages are passed in the context of the aggregated message.
Connected gateways
The internal gateway where to send the aggregated message. You can select multiple gateways in. A copy
of the message will be sent to each of them.
Aggregation type
Select 'append' for simple append. Use header, separator and footer to control the aggregation. Select 'xml'
to create an aggregation of xml document. Optionally an xslt can be applied to the result. Select 'edifact' or
'x12' to merge edi documents; the envelope of the first document will be used. Select 'zip' to wrap messages
in a single zip file.
Group by
Optional. Enables to generate different aggregated files grouping incoming messages based on the value of
a metadata. Example: 3 messages arrive with value A, B and A in the selected metadata. The aggregator
will generate 1 file with the 2 messages with value A and 1 file with 1 message with the value B.
Frequency
Frequency in seconds. Default is 300 (5 minutes).
102
Channels
Cron expression
* MON-FRI). This takes precedence on the frequency property. For easy creation of your cron expression,
you can use the online cron maker tool available at: http://www.cronmaker.com/. For more information,
please refer to the following page: http://www.quartz-scheduler.org/docs/tutorials/crontrigger.html.
Input filename
Filename of the message OUT of the channel that serves as input to the aggregator, by default this is the
same as the message in.
Output filename
Filename of the aggregated file, by default the file name is set to 'aggregate'. Tip: You can use:
{com_babelway_messaging_context_aggregator_groupBy} to include the name of the group by in the file
name, or any user defined metadata defined in the first of the aggregated messages.
Minimum idle time
If you specify a time (in seconds), the aggregation will wait that time after the reception of a new incoming
message, even if it conflicts with its scheduled run. This allows, for example, ensuring all messages from a
batch are included in a single aggregation.
Header
For 'append' type: prefix to add at the beginning of the file. For 'xslt' type: name for the root of the resulting
message. Default='messages'
Separator
For 'append' type: message separator. For 'xslt' type: name for the element surrounding each message. Default='message'
Footer
Suffix to add at the beginning of the file.
Xslt
Xslt to execute on the resulting Xml.
Edifact skip UNA
Check this to skip the UNA section in EDIFACT and Odette messages.
Edifact control
Define a custom XPATH expression used to compute the edifact control field. If left empty, the control of
the first message will be used.
Input charset
Charset to use to decode the file waiting to be aggregated. Default is UTF8.
Output charset
Charset to use to encode the file resulting of the aggregation. Default is UTF8.
gateways.
NFS Gateway
The NFS gateway is used to connect and push files to a remote NFS server.
103
Channels
Server
Hostname of the NFS server.
Export
Name of the exported volume.
Login method
NFS login method: use PCNFSD for username / password and UGID to directly use UID, GID and GIDS
Username
Username used for the NFS authentication. Only used with PCNFSD login method.
Password
Password used for the NFS authentication. Only used with PCNFSD login method.
User uid
Unix user UID to use during authentication. Only used with UGID login method.
User group gid
Unix user's group GID to use during authentication. Only used with UGID login method.
User extra group ids
Unix user's additional groups GID to use during authentication, encoded as a comma separated list. Only
used with UGID login method.
Directory
Local NFS path to the folder you want to use. This is relative to the export.
Lookup Table Out Gateway
The lookup table gateway is used to fill a lookup table automatically from a message.
Lookup Table Id
The technical id of the lookup table.
Append
Check this if you need to append the records contained in the messages going through this channel. Otherwise, the entire table will be replaced by the new values.
Criteria
If filled, only the values that match this criterion will be deleted or inserted in the target lookup table. The
name must be the name of the column that must match. The value is the value that this column must have
to be replaced.
SAP Gateway Out
With a SAP Out Gateway, outgoing messages are pushed from Babelway to a SAP server.
SAP client
SAP client to use. This is the three digit number you use in the first field of the login screen of SAP Gui. It
has the name 'Client' and is just above the user and password fields. For instance: 001, 210, 400 ...
104
Channels
User
The Valid SAP user ID you want to use. Ideally this should be a user specially created for this purpose. For
instance: user
Password
Password associated with the user ID. For instance: password
Server address
IP or DNS name for SAP application server. For instance: sap.yourcompany.com
SAP system number
SAP system number is the last 2 digits of the SAP client. For instance: 01, 10, 00. Default is the last 2 digits of SAP client parameter
Dropbox Gateway Out
The Dropbox gateway out allows you to upload your messages into a Dropbox account.
Dropbox account
The name of the Dropbox account to which the messages will be sent. This information is "read only", and
set by the wizard when you allow Babelway to access the Dropbox account.
Folder
The folder in your Dropbox account in which the messages will be placed. This folder will appear under the
path /Applications/Babelway/ .
Exact Out Gateway
The Exact gateway allows to send messages to Exact Postbox users. This gateway must be used with the Exact
wizard and the message delivery is based solely on the content of the message sent.
Tradeshift Out Gateway
This gateway allows you to send files directly to an account on Tradeshift.
API Prefix
URL Prefix to call Tradeshift API. Default is https://api.tradeshift.com/tradeshift/rest/
Connection type
Choose 'Tenant' to connect to your own Tradeshift account and send the document from there. Choose
'Van' if you don't have a Tradeshift account and you need to dispatch the document to the account of
someone else.
Tenant Id
The Tradeshift tenantId to use. Use Babelway application in Tradeshift to retrieve this value.
Token
The Tradeshift token to use. Use Babelway application in Tradeshift to retrieve this value.
Secret
105
Channels
The Tradeshift token secret to use. Use Babelway application in Tradeshift to retrieve this value.
Consumer key
The Tradeshift consumer key to use to authenticate the Babelway application. This should be left empty in
most of the case.
Consumer secret
The Tradeshift consumer secret to use to authenticate the Babelway application. This should be left empty
in most of the case.
Retry on http return code
Comma separated list of error Http return code that should be retried. If the return code is not in the list, the
message is set in error. The default is '502,503,504'.
API suffix
The Tradeshift API to call. Do not include the URL prefix.
Http Method
You can specify the http method to call. The default is PUT.
Request content type
The content type of the generic api request. The default is text/xml.
Response content type
The content type of the generic api response. The default is text/xml.
Connected gateway
Select zero, one or several gateways to receive the response from the Tradeshift API.
Document Profile
The Tradeshift document profile.
Van
The van id used by Tradeshift to find the business partner.
Country
The country used by Tradeshift to find the business partner.
Company Name
The company name used by Tradeshift to find the business partner.
Email
The email address used by Tradeshift to find the business partner.
Identifier Scheme
The identifier scheme used by Tradeshift to find the business partner.
Identifier Value
The identifier value of the scheme used by Tradeshift to find the business partner.
Additional query parameters
Key value pairs which will be added to the request.
Retry strategy
106
Channels
Connected Gateways
Select zero, one or several gateways to receive the response from the server.
gateways.
Amazon Marketplace Out Gateway
This gateway allows to send 'Feeds' to an account on Amazon Marketplace.
Process
Request [email protected] for changing this parameter. Type of process. 'Feed' is the only one supported at this stage.
Endpoint
Request [email protected] for changing this parameter. Endpoint is the entry point for an Amazon
marketplace web service. Default is https://mws.amazonservices.com
Access key
Amazon marketplace web services access key ID.
Secret key
Amazon marketplace web services secret key ID.
Seller Id
Amazon marketplace seller ID.
Marketplace Id
Amazon marketplace ID.
Feed type
Feed type see MWS doc.
Retry strategy
Billtrust Out Gateway
With an BilltrustOut Gateway, outgoing messages are sent to Billtrust API.
All the user defined metadata defined in the messages are passed in the context of the new message.
Url
Login url
URL used to get OAUTH2 token.
Username
107
Channels
Password
Connected gateway
error. The default is '200,201,202,204,205'.
Success expression
Response filename
Filename
Timeout
Http Method
You can specify the http method to call. The default is POST.
Http headers
Trust level
VAN Out Gateway
This gateway allows you to send files directly to ECGrid VAN.
The VAN gateway routes the message to its destination based on the Identifier / Qualifier pair as determined in
the X12 or Edifact data.
1. The Receiver ID is known in the VAN database. If this is the case, your message will transmit properly to
your receiver. The message will be successful.
Filename
108
Channels
Once this is complete, you may begin using the channel to send to your trading partner.
PEPPOL Out Gateway
This gateway allows you to send files to the PEPPOL network.
Nothing is needed to be set up except that the receiver needs to be registered in the SML. Please contact [email protected] if you want to perform some tests with SMP or AP not registered in the SML.
More information about PEPPOL in Gateway IN section
PEPPOL environment
Choose between the regular PEPPOL production infrastructure, connected to the SML, or the test infrastructure, connected to the SMK. The default is Production
RosettaNet Out Gateway
This gateway allows you to send RosettaNet complient PIP message to another RosettaNet Server. This Gateway must be used along with a RosettaNet message out.
Url
URL of the RosettaNet server of the receiver.
Attachment patterns
Attachments to add to the S/MIME message. Metadata = Pattern to match metadata containing the file to
attach. Filename = name of the file in the zip. If one pattern matches multiple files, it is possible to put
them all if you guarantee to generate a different filename name for each. This can be achieved by using the
capturing groups of the regex in the filename. Ex: if your metadata pattern is attachment-(.*) and your filename is \1, processing with two metadata attachment-file1.csv and attachment-file2.csv will result in files
file1.csv and file2.csv.
Test flag
Select this to set the GlobalUsageCode in the ServiceHeader to 'Test'. Otherwise 'Production' is used.
NemHandel Out Gateway
This gateway allows you to send messages to the Danish NemHandel network.
Registration certificate
Select the certificate use to register your information into the NemHandel registry.
NemHandel environment
Choose between the regular NemHandel production infrastructure, or the test infrastructure. The default is
Production
109
Channels
Retry strategy
4.3. Message definitions
This section contains all the tools needed to manage your message definitions. A simplified edition of the message definitions is directly available in the channels overview, but you need to come to this section to have access to all functionalities.
Message definitions describe in Babelway the format (CSV, XML, EDIFACT, ...) and the structure (all the
fields) of an exchanged file.
Each channel contains 2 message definitions:
• Message in is used to describe the files received by Babelway from the source external system.
• Message out is used to describe the files that Babelway must send to the target external system.
4.3.1. Message definitions list
The List of Message definitions screen shows you all the message defitnions defined within your environment,
even if they are not used in any channel. From here, you can easily edit them, or create new ones.
This screen is accessible by clicking on the menu Channels, then the sub-menu Message definitions
Name
Description
Direction
IN for message definitions In, or OUT for message definitions Out.
Type
The type of the message definition. See message definitions types for all possible values.
Created on
The date and time when the message definition was created.
Last updated on
The date and time of the last modification of the message definition.
You can click on a line to view the details of the associated message definition, or edit it. See message defini110
Channels
tion details.
The Create message definition action button allows you to create new message definitions.
4.3.2. Creation of a message definition
To create a new message definition, you have two main options:
• Create it from scratch.
• Duplicate an existing message definition (from your environment, or from the Babelway catalogue).
You can access this choice by clicking on Create a message definition in the message definitions list screen, or
directly from the channel detail screen.
Create a new Message Definition.
To create a Message Definition, you have first to select the type of gateway that you want to use (CSV, XML,
Edifact, ...).
Figure 4.29. MessageDefinition creation - Type choice.
Then you need to follow the instructions on the screen. The parameters depend on the type of MessageDefinition selected. You can find detailed explanation of every type in the section on MessageDefinition formats..
111
Channels
Figure 4.30. MessageDefinition creation - CSV.
Figure 4.31. MessageDefinition creation - XML (step 1).
Reuse an existing MessageDefinition.
The other solution is to select an existing MessageDefinition from the "Reuse and Save time" zone.
112
Channels
Figure 4.32. MessageDefinition creation - Reuse
113
Channels
When you are in the Channels section, and you reuse a MessageDefinition that is already used in other channels, you will have the choice to share the MessageDefinition, or to make a copy.
Figure 4.34. Gateway creation - Share or Copy
More details can be found in the Reuse and Save time section.
4.3.3. Message definition detail
This page shows all the details about a message definition, and gives access to all operations that can be made
on a message definition.
This page can be accessed from the message definitions list, or by following any link that refers to a message
definition.
General
The general tab contains the general information of the gateway, and offers actions that act on the whole message definition.
Direction
Field used to indicate if the message is coming in the system or leaving it.
Type
Type of the message definition (CSV, XML, EDIFACT, ...)
Name
Description
Id
114
Channels
Created On
Last Updated On
Tree
The tree describes the structure of the message, with all its fields. It is displayed in graphical form.
For more details, see all information about the message definition tree.
Don't forget to save when you're finished with your changes.
Properties
This screen allows you to configure all the options of the message definitions. Some of these options are common. Others differ depending on the message definition type.
See the message definition common options for further information on common message definition properties.
See the message definition types section to learn more about the options for each message definition type.
Extra processing
The extra processing allows you to configure additional processes that must be applied on the messages. Some
examples are extracting the file from a zip file, or signing the output file.
See extra processing section for the description of every available extra processing, and all their parameters.
Related items
This tab contains quick links to many other elements related to this message definition.
Using channels
Parent
Children
Using transformations
List of transformations using this message definition.
Change Log
This tabs shows you all the history of changes on this message definition, and allows you to revert to a past version. For more details, see the change log section.
4.3.4. Update the message definition tree
115
Channels
Once a new message format has been saved or during edition of existing messages, the message tree is rendered
in the Visual Editor in a hierarchical and graphical form as illustrated below.
In Visual Editor, you can further configure and set up message format as well as add verification rules as explained in following sections.
Figure 4.35. Message edit screen
Left panel - understand tree structure
The left part of the screen shows the structure of the message, as a tree. It describes all the elements that the
message format may contain.
Note
People familiar with xml files will find many similarities between the tree definition used here and the
structure of a xml file. The reason is the following: In Babelway, all message formats are first translated into xml, that is used to apply all message transformations. The structure defined here is in fact
the xml representation of your message.
116
Channels
Figure 4.36. Structure of message
The tree uses different types of nodes:
• (1) A value node is just a "normal" node. It corresponds to one element in the message format that we are
describing. It can just contain a value, or also be a structural element that contains other nodes.
•
represents an element in the corresponding xml.
•
represents an element in the corresponding xml, that contains a fixed static value.
•
represents an attribute in the corresponding xml.
•
represents an attribute in the corresponding xml, that contains a fixed static value.
Note
A message item will be defined as an xml element or attribute depending on xml generation or translation tool that has been used. The main difference for Babelway platform is that an attribute is unique
and cannot be repeated inside an element. So you cannot use loops with these attribute items.
• (2) Other nodes are virtual nodes. They do not have any correspondence in the messages, but are used to tell
additional information to the Babelway platform, like the fact that some elements can be repeated, or have
possible structure alternatives.
•
represents a loop node. It means that its content can be repeated multiple times.
•
and
indicate that the message can have multiple alternatives. The first icon is used to group all
choices, and the second one for every option.
Right panel - edition of element node
117
Channels
The right part of the screen shows how the details about the selected node. From there, you can edit all the
properties of the node, or make actions on it to change the structure of the tree (delete, duplicate, ...).
118
Channels
Figure 4.37. Details of selected node
General parameters are:
Label
The label is the text used to show this node in the message definition tree. It can be changed freely, as it has
no impact on the processing of the messages.
Description
The description allows you to save some more documentation about this node.
Name
The name identifies the element in the xml representing the messages. Change only with care.
Default value
Only for message definition OUT. The default value will be used in the message out for this field if no
mapping is done for this field.
Filter value
Only for message definition IN. When this value is filled, only the records with this precise value will be
used.
You can also add validations on nodes. The validations are assertions that will be checked when we receive a
message in this format, or before we send a message in this format. If one of the validations fails, it means that
the message does not comply with the definition, and the message will be put in error.
Note
We strongly recommend that you fill the validations, and reject messages that are wrong. If you don't
enforce validations, there is a big risk that you send to the receiving partner files that are not correct,
because your mapping will probabaly not foresee all of these cases. Validations on message OUT will
also allow you to detect early problems in your mappings, detecting it immediately when one of your
mapping generates a message that do not comply with the definition.
The following validations are available:
Mandatory
When a field is marked as mandatory, it must have a non-empty value. From the xml point of view, it
means that the element must be present, and may not be empty.
Type
Type of the data in the field (String, Number, Date, ...). This field will also affect the other validations that
will be available.
Length (only for Strings)
Min or Max length (in characters) for the value.
Regexp (only for Strings)
Regular expression that the value must match.
Min/max value (only for Numbers)
Indicates that the number value must be between the two given limits.
119
Channels
Format (only for Dates/Datetimes)
Format that are accepted, like 'yyyy/MM/dd', ... Full description of accepted formats can be found at ...
Multiple allowed formats can be entered, separated by a comma.
Custom
Custom xpath expressions that the value must match (if non-empty).
Appearance in output file is enabling you to decide the conditions in which the selected element will appear
in the output file.
Here are all the possible conditions:
Always
This element will always appear in the output file whether or not it's filled or not.
If at least one non-default sub-element appears
This element will appear if at least he has a value or if one of his non-default sub-element decided to appear. By non-default, we mean an element which doesn't have a default value. In short, only structural subelement (white) and non-default field (blue).
Example of element that will appear in the output:
Figure 4.38. One out of two blue sub-element mapped
Figure 4.39. One blue and 1 green sub-element
Figure 4.40. 1 structural sub-element appears out of 3 sub-elements.
120
Channels
Figure 4.41. 1 attribute sub-element appears.
Example of element that will NOT appear in the output:
Figure 4.42. Two green sub-elements (because they are default values).
Figure 4.43. One blue with no value and one green sub-elements.
If all sub-elements appear
If all sub-elements decided to appear in the output file
Example of element that will appear in the output:
Figure 4.44. All blue sub-elements
Example of element that will NOT appear in the output:
Figure 4.45. Two green sub-elements or One blue not filled and one green
121
Channels
Figure 4.46. Only one out of two blue sub-elements
Not Empty
(applies only to element without children) Will appear in the output file if it has a value.
Search
On the top of the left panel, a search bar allows you to easily find nodes in big documents.
Figure 4.47. Search
To search nodes, just type part of the name that your searching.
122
Channels
• All the items that match will be highlighted.
• The first matching item will be selected, and details shown in right panel.
• Numbers of matching items will be displayed, with arrows to iterate between matches.
• If needed, tree will be opened, or scroll will be adjusted, so that current match is made visible.
Updating tree structure
Figure 4.48. Search
To update the tree structure, you have different possibilities
• When a node is selected, all actions that apply to this node are available on the bottom of the right panel.
You just have to click on it to call the wanted action.
• Move operations can be done immediately in the tree, by just drag-and-dropping your node to the new selected validation. Duplication can be done the same way, by pressing the Ctrl key before the drag.
Managing Choice
You can create choice to manage conditional processing of your message definition.
To identify a node or a set of nodes that can have several alternatives in its structure and/or value, you need to
enclose the set of related alternatives within a Choice node and each alternative branch into an Option node.
A Choice node is a virtual node identifying alternative branches. Each alternative branch is a possible option
and is represented by an Option virtual node as illustrated in the following example:
123
Channels
Figure 4.49. Example of a choice
There are two Choice nodes, one for the buyer's information, that accepts either a company structure with a
VAT number value, or a person structure with firstname, lastname and address values. The other Choice node
is for the price of an Item, it can accept either a price with a 0% or a 21% VAT.
In this latter case, both alternative branches have the same structure, but they have different static values (0 or
21) for their VAT node (static value nodes are green).
It is mandatory that each Option of a Choice is uniquely identifiable compared to each other. They could be
identified by having different structures (like the buyer's Choice example) or by having the same structure with
different static values (like in the price Choice example).
Managing Loops
Create loops to manage repetitive parts of your message definition.
Loops and grouping
A message is based on three node types as defined in the Message Definition chapter.
To specify that a value or a structural node can occur more than once, you need to enclose it in a Loop. A Loop
is a virtual node representing the multiplicity of a node or a set of nodes. It is defined by its minOccurs and
maxOccurs properties:
• MinOccurs defines the minimum number of repetition of the node or the set of nodes that should occur. It
124
Channels
may be 0 or any positive number.
• MaxOccurs defines the maximum number of repetition of the node or the set of nodes that should occur. It is
either a positive number or the value " unbounded " (that represents an undetermined number of repeat).
CSV Sample:
By definition a CSV message is composed of a header containing some header items, followed by one or many
lines containing line items. The number of line items correspond to the number of header items.
header1,header2,header3,header4
123,aaa,abc,000
456,bbb,def,111
789,ccc,ghi,222
...
Here is the message tree for this CSV:
Figure 4.50. Message tree
The headers and line nodes are structural nodes, while header and line items are value nodes. To specify that
the line can appear more than once, there is a virtual Loop node enclosing the line node.
Grouping
A Loop can define the multiplicity of a node sequence. To identify a node sequence in a Loop, you must manually group those relevant nodes using one of the following grouping types:
• Group By: groups together all nodes that have the same value as the Grouping value.
• Group Adjacent: groups together all nodes that have the same value as the Grouping value, provided that
they are also adjacent in the message sequence.
• Group Starting With: processes the nodes in the supplied sequence in turn, starting a new group whenever
one of the node matches the Grouping value.
• Group Ending With: processes the nodes in the supplied sequence in turn, closing the current group whenever one of the node matches the Grouping value.
Loop parameters can be edited by right-clicking on the loop node in the message tree in the In or Out message
125
Channels
tab during channel editing.
Figure 4.51. Loop parameters
The grouping value is an XPath expression identifying the grouping pattern.
By right clicking on any node, you can:
• Create Loop: to enclose the selected node in a new loop node.
• Remove from Loop: to remove the selected node from its parent loop.
• Put in next/previous Loop: if the selected node is adjacent to a loop node you can make it join that loop to
create a multiplicity on a nodes sequence (in that case, specify a Grouping value ).
Regrouping a Loop
An existing loop can also be regrouped using one of the Grouping type. To do this you can use the Regroup this
Loop in the loop contextual menu. This will create a new enclosing loop that requires specifying the Grouping
type and the Grouping value.
Example with a DESADV message in a CSV format:
TruckId,PalletId,PacketId,Quantity,Item
1,
1,
1,
5,Item 1
1,
1,
1,
25,Item 2
1,
1,
1,
1,Item 3
1,
1,
2,
3,Item 4
1,
1,
2,
15,Item 5
1,
2,
1,
100,Item 6
1,
2,
1,
2,Item 7
1,
2,
3,
20,Item 8
1,
2,
3,
11,Item 9
1,
2,
3,
9,Item 10
1,
2,
4,
72,Item 11
2,
1,
1,
91,Item 12
2,
2,
1,
423,Item 13
2,
3,
1,
88,Item 14
2,
4,
1,
3,Item 15
3,
1,
1,
12,Item 16
3,
1,
1,
21,Item 17
3,
1,
1,
666,Item 18
3,
1,
2,
3,Item 19
3,
1,
2,
22,Item 20
3,
1,
2,
2,Item 21
3,
2,
1,
211,Item 22
3,
2,
1,
64,Item 23
126
Channels
4,
4,
4,
4,
4,
5,
1,
1,
1,
1,
1,
1,
1,
1,
2,
2,
2,
1,
61,Item
17,Item
2,Item
9,Item
85,Item
57,Item
24
25
26
27
28
29
Figure 4.52. Default message tree
In this example, we have a loop of lines defining an item to dispatch, where each line has the truck id for where
the item is stored.
We could regroup this loop of lines by TruckId so that we can loop on all trucks and then loop inside each truck
on all the items in that truck.
To do that we select the Regroup this Loop action on the loop, select the Group By value for Grouping type and
set it to ' field[1] ' (as this is the XPath of the TruckId element).
Figure 4.53. Regroup this loop
We now have a loop on all trucks and a sub loop on all the items in the truck.
127
Channels
Figure 4.54. Sub loop
We can even go further and decide to group by PalletId and PacketId, that would give us four nested loops, one
for all trucks, the next one for all pallets in a truck, the next one for all packets in a pallet and the last one, for
all items in a packet.
Figure 4.55. ...
4.3.5. Message definition formats
This list shows main message formats supported by the application.
• CSV
• EDIFACT
• X12
• Odette
128
Channels
• XML
• Excel
• PDF based on XHTML template
• Flat-file
• Multirecord
• Tradacom
• Json
• Rest
• SAP Idoc flat file
• Generic
• Not Defined
• UBL
• RosettaNet
CSV
A CSV or comma-separated values file is used for the digital storage of data organized in a table form. Each
line in the CSV file corresponds to a row in the table, and within a line, fields are separated by commas (or
semicolons, colons or tabs), each field belonging to one column of the source table.
As this is a very common and simple file format, CSV files are often used to move tabular data between different computer programs, such as between a database and a spreadsheet program.
File sample
Following is a sample CSV file.
NAV Date,ISIN,Fund Name,Share Typ,Fund Ccy,NAV in Fund Ccy,Bid Price in Fund Ccy,Offer Price in Fund C
06/13/2008,LU0223208157,HSBC GIF EMERGING EUROPE EQUITY,AC,EUR,15.088,15.088,15.924,12190498.17,807980
The following properties are available:
Delimiter character
The character that is used to separate the fields in the csv. It can be a comma, colon, semicolon or tab.
Quote character
The character that is used to quote the specials characters in the csv. It can be a single quote (') or a double
quote (").
Headers
Tells you if the csv file begins with a line that contains headers of the columns, or directly begins with the
lines of data.
Encoding
129
Channels
The encoding of the csv file.
Sample
An example of CSV file handled by this message definition.
Edifact
Introduction
United Nations / Electronic Data Interchange for Administration, Commerce and Transport (UN/EDIFACT) is
the international EDI standard developed under the United Nations impulse. This standard is maintained and
further developed by a UN body. EDIFACT has now been adopted by the International Organization for Standardization (ISO) as the ISO standard ISO 9735.
The EDIFACT standard provides a set of syntax rules to structure data, an interactive exchange protocol
(I-EDI), and standard messages which allow multi-country and multi-industry exchange.
You
can
find
more
information
about
Edifact
on
its
offical
site
(
http://www.unece.org/cefact/edifact/welcome.html ) or on Wikipedia ( https://en.wikipedia.org/wiki/EDIFACT ).
Below is a sample EDIFACT file.
UNB+UNOA:1+005435656:1+006415160:1+060515:1434+00000000000778'
UNH+00000000000117+INVOIC:D:97B:UN'
BGM+380+342459+9'
DTM+3:20060515:102'
RFF+ON:521052'
NAD+BY+792820524::16++CUMMINS MID-RANGE ENGINE PLANT'
NAD+SE+005435656::16++GENERAL WIDGET COMPANY'
CUX+1:USD'
LIN+1++157870:IN'
IMD+F++:::WIDGET'
QTY+47:1020:EA'
ALI+US'
MOA+203:1202.58'
PRI+INV:1.179'
LIN+2++157871:IN'
IMD+F++:::DIFFERENT WIDGET'
QTY+47:20:EA'
ALI+JP'
MOA+203:410'
PRI+INV:20.5'
UNS+S'
MOA+39:2137.58'
ALC+C+ABG'
MOA+8:525'
UNT+24+00000000000117'
UNZ+1+00000000000778'
Extensive support
Babelway supports all Edifact messages, and knows all the definitions of the different norms. This knowledge
of these definitions will allow additional functionnalities when you work with Edifact. Amongst other things :
• By just loading a sample Edifact file, Babelway wil be able to deduce the structure, find the definition of the
elements, calculate human-readable labels, ... You can see on the following screenshot the result when you
load the sample above.
130
Channels
Figure 4.56. Edifact tree just after having loaded a Sample.
• Adding or removing segment elements is very easy, as the interface knows precisely which elements may
take place in the selected segment.
131
Channels
Figure 4.57. Edit segment shows all the possible elements.
• In the same way, segments can be easily added. The interface will offer you segments and elements that may
take place at this location.
132
Channels
Figure 4.58. Edit segment shows all the possible elements.
• Messages can be validated deeply (structure, mandatory fields, values, ...) automatically, without having to
define any validation manually.
• For all the runtime messages, comments are added in the internal representation to ease the reading of the
file.
133
Channels
Figure 4.59. Internal representation of an Edifact.
Properties
Validate structure
Only for messages OUT. If yes, an error will be generated if your message has an incorrect structure. Desactivate only if you really want to send messages with incorrect structures.
Validate values
If yes, all values will be checked against their definition. Desactivate only if you really want to receive/send
messages with values that do not respect the Edifact standard.
Validate segments
If yes, all segments will be checked against their definition (mandatory fields must exist, no field can be
present if not in definition). Desactivate only if you really want to receive/send messages with values that
do not respect the Edifact standard.
Sample
An example of Edifact file handled by this message definition.
UNA segment
Only for messages OUT. The UNA segment to be used in your output message. If you asked for an empty
UNA segment, it will not be printed, and default separators will be used. If you specify one, rest of file will
be written accordingly, adapting to the separators defined in the segment.
134
Channels
Add line breaks between segments
Only for messages OUT. If yes, an additional line break will be added in the output message between every
segment. Only for human readability.
X12 Message Format
ASC X12 (also known as ANSI ASC X12) is the official designation of the U.S. national standards body for
the development and maintenance of Electronic Data Interchange (EDI) standards. ASC X12 has sponsored
more than 315 X12-based EDI standards for health care, insurance, government, transportation, finance, and
many other industries.
Babelway supports all X12 messages, and offers the same extensive support as for Edifact.
File sample
Below is a sample X12 file.
ISA*00*
*00*
*ZZ*SENDERISA
*ZZ*RECEIVERISA
GS*IN*SENDERDEPT*007326879*19960807*1548*000001*X*004010~
ST*810*000000001~
BIG*20090927*00027**A00027-01~
N1*ST*CHOCOLATE IMPORT*9*1234567890~
N3*1000 N. NORTH HIGHWAY~
N4*NEW YORK*NY*10310~
N1*BT*RETAILER INC.*9*1098765432~
N3*P.O. BOX 0000~
N4*LAKE*VA*20120~
N1*RE*FOODSELLER*9*12345QQQQ~
N3*P.O. BOX 222222~
N4*FAIRFAX*VA*94978~
ITD*01*3*1**15**16~
FOB*PP~
IT1**16*CA*12.34**UA*006540022222~
PID*F****BELGIUM CHOCOLATE~
IT1**13*CA*12.34**UA*006540033333~
PID*F****SWISS CHOCOLATE~
TDS*35786~
CAD*****FREEFORM~
ISS*29*CA~
CTT*2~
SE*22*000000001~
GE*1*000001~
IEA*1*000000020~
*960807*1548*U*00401*000000020*0*
Validate structure
Only for messages OUT. If yes, an error will be generated if your message has an incorrect structure. Desactivate only if you really want to send messages with incorrect structures.
Validate values
If yes, all values will be checked against their definition. Desactivate only if you really want to receive/send
messages with values that do not respect the Edifact standard.
Validate segments
If yes, all segments will be checked against their definition (mandatory fields must exist, no field can be
present if not in definition). Desactivate only if you really want to receive/send messages with values that
do not respect the Edifact standard.
135
Channels
Sample
An example of Edifact file handled by this message definition.
Edi template
Template of output file, that will be used to choose delimiters.
Output Charset
Charset to use to encode the file.
Input Charset
Charset to use to decode the file.
Odette
The Organization for Data Exchange by Tele Transmission (ODETTE) in Europe is a group that represents the
interests of the automotive industry in Europe. They are the equivalent of the Automotive Industry Action
Group (AIAG) in North America.
ODETTE has been responsible for developing communications standards such as OFTP and OFTP2.0
Babelway supports all following ODETTE Messages:
AVIEXP, AVIGRU, AVIREX, BASDAT, CONFOR, CONTRL, CREDIT, DEBNOT, DELINS, ENQIRY,
FORDIS, GRUDES, INVOIC, KANBAN, MODPRI, OFFERR, ORDERR, OSTENQ, PRILST, REMADV,
REPDEL, REPINV, REPORD, STATAC, STOACT, SYNCRO, SYNPAC
File sample
Below is a sample ODETTE file.
UNB+UNOA:1+1111:OD+2222:OD+980611:1723+888++KANBAN'
UNH+1+KANBAN:2::OD'
MID+0000001266+040331:0001'
CDT+::::::2474'
BDT+0931955500293'
CSG+0931955500293+I'
ARD+190569'
KDE+:336+3840++040402:1648'
ARD+192209'
KDE+:492+1600++040402:2057'
UNT+10+1'
UNZ+1+888'
Edi Template (Only available for Odette Out)
The template is used by the EdiWriter in order to define the proper layout of the odette and follows the syntax of the template.
Skip UNA (Only available for Odette Out)
Check this to skip the UNA section in ODETTE.
Output Charset
Input Charset
136
Channels
Sample
An example of ODETTE file handled by this message definition.
XML
XML stands for eXtensible Markup Language and is a very common type of files.
File sample
Below is a sample XML file.
<?xml version="1.0"?>
<Document>
<SenderID>5420008199981</SenderID>
<ReceiverID>5400102000086</ReceiverID>
<DocumentDate>20080531170538</DocumentDate>
<DocumentNumber>VK20084010</DocumentNumber>
<TestIndicator>P</TestIndicator>
<DocumentLanguage>NL</DocumentLanguage>
<Version>1.1/Food</Version>
<Invoice>
<MessageReferenceNumber>VK20084010</MessageReferenceNumber>
<InvoiceHeader>
<MessageType>INV</MessageType>
<MessageNumber>VK20084010</MessageNumber>
<MessageFunction>ORI</MessageFunction>
<InvoiceCurrency>EUR</InvoiceCurrency>
<Dates>
<InvoiceDate>20080531170538</InvoiceDate>
<AccountingValueDate>20080531170538</AccountingValueDate>
<DeliveryDate>20080530170738</DeliveryDate>
<OrderDate>20080530170538</OrderDate>
</Dates>
</InvoiceHeader>
<InvoiceDetail>
<InvoiceItem>
<ItemType>GDS</ItemType>
<LineItemNumber>1</LineItemNumber>
<EANArticleNumber>95400102057205</EANArticleNumber>
</InvoiceItem>
</InvoiceDetail>
</Invoice>
</Document>
Output Charset
Charset to use to encode the file
Input Charset
Charset to use to decode the file
XSD
Xsd definition file corresponding to the XML message.
XsdImports
Xsd Imports that the Xsd definition depends on.
Sample
An example of XML file handled by this message definition.
137
Channels
If you want to create and XML message definition, we advise you to provide a complete XML sample and
XSD file(s) defining the structure of the XML. You will get validation, documentation, loop generation from
XSD files and the resulting message definition will be limited to fields present in the XML sample.
If you provide XSD files only, be aware that, if XSD structure is fairly complex, the resulting message definition will be very difficult to use.
If you provide an XML sample file only, you will need to manually edit the message definition to add the
'loops' where it makes sense.
Excel Message Format
File sample
Below is a sample Excel file having headers at the first row of the Excel sheet.
Figure 4.60. Excel Sample file
Excel version (Only available for Excel In)
Which Excel format is used (XLS or XLSX).
Ignore empty lines (Only available for Excel In)
Check this to ignore empty lines.
Trim (Only available for Excel In)
Check this to removes all spaces from text except for single spaces between words.
Dateformats (Only available for Excel In)
Used date format.
SheetMode (Only available for Excel In)
Single/Multiple sheets? if not selected, only first sheet of workbook is considered.
ExcelTemplate (Only available for Excel Out)
The template is used by the ExcelWriter in order to define the proper layout and formats of the generated
Excel.
Headers
Select if first row contains field headers.
138
Channels
Encoding
Charset to use to encode/decode the file.
Sample
An example of Excel file handled by this message definition.
File sample
Babelway Excel wizard only supports the Excel files with extension ".XLS"
So if the Excel file you are intended to use has an extension ".XLSX", you will have to change the Excel extension to ".XLS" before uploading it in the Excel wizard. Here is the procedure.
*Excel file extension modification procedures.
1-Open you Excel file with extension ".XLSX" and the press "save as".
Figure 4.61. Press save as
2-Open "Save As type" drop down menu and choose the extension XLS and press save.
139
Channels
Figure 4.62. Save file with a new extension
PDF based on XHTML template Message Format
PDF Wizard screen allows you to define your PDF message format based on your XHTML template file.
To define a message in PDF format, select an existing template or make a copy of the generic PDF template in
the catalogue and the following screen will be displayed.
Wizard screen
When you create a new message format, you must first configure it using the following wizard.
Figure 4.63. PDF Wizard screen
A PDF message can only be set up using a template file in XHTML format. Select your template file using the
Browse... button next to the XHTML file, then click on the Upload command.
File sample
Below is a sample PDF file.
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>PDF output</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
<style>
@page {
@page {
@page {
@page {
size: A4; margin: 3cm 1.5cm 2cm 1.5cm; border: none; padding: 1em; }
@top-left{content: ""; }}
@top-right{content: "Page " counter(page) " on " counter(pages);}}
@bottom-left{content: element(footer);border-top: solid 0.01mm #000; }}
#footer{display: block; position: running(footer); }
</style>
</head>
<body style="font-size: 12pt; font-family: 'Nobile'">
<center>
<h1 >PDF output example</h1>
</center>
140
Channels
<br/>
<div style="font-size: small">
<span>Date :</span>
<span id="invoiceDate">25-08-2009</span>
</div>
<br/>
<center style="font-size: large">Example</center>
<br/>
<table style="width: 100%" >
<tr>
<td rowspan="1" style="width: 200px; height: 20px;">
<span>Invoice number :</span>
<span id="invoiceNumber">field1</span>
</td>
<td style="width: 300px; height: 20px;">
<span>Contact Name :</span>
<span id="firstName">field2</span>
<span id="lastName">field3</span>
</td>
</tr>
</table>
<br/>
<center>
<span>Some static info</span>
</center>
<table style="width: 100%" dir="ltr" frame="box">
<tbody>
<tr>
<td bgcolor="#cdd5cb" rowspan="1"
style="width: 120px; height: 30px;">Description</td>
<td bgcolor="#cdd5cb" style="width: 80px; height: 30px;">Unit price</td>
<td bgcolor="#cdd5cb" style="width: 40px; height: 30px;">Qty</td>
<td bgcolor="#cdd5cb" style="width: 80px; height: 30px;">Vat rate</td>
<td bgcolor="#cdd5cb" style="width: 100px; height: 30px;">Tax free
price</td>
<td bgcolor="#cdd5cb" style="width: 80px; height: 30px;">Tax</td>
<td bgcolor="#cdd5cb" style="width: 80px; height: 30px;">Total price</td>
</tr>
<tr id="product-loop">
<td style="width: 120px; height: 20px;" rowspan="0"><span
id="itemDescription">Support pack 5h</span> </td>
<td style="width: 80px; height: 20px" align="right"><span
id="itemUnitPrice">425.00</span> </td>
id="itemQuantity">1</span> </td>
id="itemVatRate">21.00</span> </td>
id="itemTaxFreePrice">425.00</span> </td>
id="itemTax">89.25</span> </td>
id="itemTotalPrice">514.25</span> </td>
</tr>
</tbody>
</table>
<br />
<center style="page-break-before:always">
<span>second page</span>
</center>
<br/>
You can upload images or css sheets as file properties and use a simple relative url in your xht
<br/>
<br/>
For specific print css options, see http://www.w3schools.com/css/css_reference.asp for all css o
<br/>
<br/>
<h2>Barcode Integration</h2>
<br/>
<barcode style="display: inline-block; width: 300px; height: 200px;" type="EAN13">123456789012
<br/>
141
Channels
<barcode style="display: inline-block; width:
<br/>
<br/>
<br/>
<br/>
<br/>
<br/>
<br/>
<br/>
<br/>
<br/>
<br/>
<div id="footer">
Footer line#1<br/>Footer line#2
</div>
300px; height: 200px;" type="EAN8">1234567890123
300px; height: 200px;" type="UPCA">1234567890123
300px; height: 200px;" type="UPCE">01234133</bar
300px; height: 200px;" type="CODABAR">A123456789
300px; height: 200px;" type="CODE39">12345678901
300px; height: 200px;" type="CODE39_EXTENDED">12
300px; height: 200px;" type="CODE128">1234567890
300px; height: 200px;" type="CODE128_UCC">123456
300px; height: 200px;" type="CODE128_RAW">123456
300px; height: 200px;" type="EAN8">1234567890123
300px; height: 200px;" type="POSTNET">1234567890
</body>
</html>
Edit screen
Once the message format template has been uploaded, or when it is used or copied from a saved format, you
have the possibility to go on the created element. If you want to edit the properties of that message definition,
switch to "Properties".
Figure 4.64. PDF Edit screen
Xhtml template
The Xhtml template which defines structure of the requested PDF.
Xhtml resources
142
Channels
Resources used inside the Xhtml template such as images, css files,...
Sample
An example of PDF file handled by this message definition.
In order to ease the navigation, the xhtml attribute id is used as the name in the resulting message definition.
These elements are visible by default. Mapping to these elements will be preserved if you upload another template containing the element with the same id.
If you need to add a loop to your xhtml, you can simply name the element with a suffix -loop like in the example above. The system will create a loop and a corresponding element. Mapping to these elements will also
be preserved if you upload a other template.
All elements without id in the xhtml will be hidden by default. If you cannot add an id to your element, you
have to manually show any element you need in the transformation step. Additionally, you should edit and rename the element label for easier management during transformation step.
To ease the search of the fields you need, the values uploaded from your example file are displayed in the field
tooltip descriptions.
See Message Definition to change show/hide parameter and edit the element label.
Multirecord Flat files
Multirecord Wizard screen allows you to define your Multirecord message format (delimited or a fixed-length)
according to your own file format.
What is mr file?
The mr file is a multirecord definition file which is used by the Self-Service MultiRecord wizard to generate the
corresponding message definition and also to build the corresponding servingxml resource file.
How to build mr file?
(1) Specify if the message is a delimited or a fixed-length.
For fixed-length messages, the mr file header will look like this:
<multirecord name="mymultirecord" type="fixed-length" lineDelimited="true" recordDelimiter="\r\n" quot
For the delimited messages the mr file header will look like this:
<multirecord name="mymultirecord" type="delimited" fieldDelimiter="," recordDelimiter="\r\n" quoteSymb
* recordDelimiter defines the delimiter between each record, it is usually the ending line character represented
on windows by \r\n, on Unix/Linux by \n and on Macintosh by \r.
* lineDelimited specifies if the system uses a record delimiter. If set to false, the record will be based on the
sum of the fields length for fixed length or the number of fields for delimited multirecords.
* trim specifies if the white spaces at the beginning and the end of the fields should be removed.
* fieldDelimiter, only used with a delimited message, defines the field delimiter.
* quoteSymbol-character is the character used to quote a field (often ")
143
Channels
* quoteSymbol-escapeSequence is the sequence that will display the quote symbol character in a quoted field
(often \")
Hint:
For multirecord as message in, do not specify recordDelimiter. The system will catch the \r or \n or \r\n. For
multirecord as message out, DO specify recordDelimiter as being for instance "\r\n"; this will generate windows compliant file and let you change the delimiter from the advanced properties later on.
(2) The second step is to write the message records definitions
You should specify the name for the record and for each of its fields. Each record should have at least one field
with a static value which will be used to identify the record.
<record name="Record1">
<field name="recordType" value="R1" width="2"/>
<field name="field1" width="5"/>
</record>
* the width is only mandatory for fixed-length messages
* value is used to specify that the field has a static value that will never change
By default all first fields with a static value are used to identify a record. But, you can also manually define
which fields must be used to identify a record using the identifier paramter.
<field name="recordType" value="R1" width="2" />
<field name="fieldA" width="5"/>
<field name="fieldB" width="3" value="BBB" identifier="true"/>
<field name="fieldC" width="7" />
<field name="fieldD" width="2" value="DD" identifier="true"/>
</record>
In this case, only the third and fifth fields (fieldB & fieldD), with identifier equals to true, will be used to identify the record. The default (without identifier=true) would only use recordType field as the identifier.
Remark:
For fixed-length messages, the fields used to identify a record should have the same position and length in each
record. No overlap between identifiers is allowed between records.
If fixed-length messages have variable length identifier per records, the only way to define it in the mr files is
to first define the smallest common length identifier for all records and then for each records that have longer
identifier, add as many as smaller field needed to unambiguously identify each record.
For example, if we have a message where AAAAA, 111 and 2222 are identifiers like as shown below:
AAAAA
contentcontent anothercontent
1112222 this and that
The following definition is not valid since the fieldA is bigger than field1 and moreover, fieldA also overlaps
with field2
<field name="fieldA" width="5" value="AAAAA" identifier="true"/>
144
Channels
<field name="fieldB" width="15" />
</record>
<field name="field1" width="3" value="111" identifier="true"/>
<field name="field3" width="20" />
</record>
It should be replaced by:
<field name="fieldA" width="3" value="AAA" identifier="true"/>
<field name="fieldA" width="2" value="AA" identifier="true"/>
<field name="fieldB" width="15" />
</record>
<field name="field3" width="20" />
</record>
We had to split the fieldA in two in order to have one fieldA with the length 3 (the same as field1) with another
fieldA with the remaining length 2.
Then the field2 (length 4) was also bigger than the second fieldA (length 2) so we also need to split it in two
field2 of length 2.
All corresponding identifier have now the same length (3 and 2) and there is no overlap between them.
It is also possible to add 4 extra parameters label, description, justify & padCharacters to each field
<field name="myField" label="My Field" description="My field description" justify="right" padCharacter
* label and description are used to display the message tree
* justify can be center, left or right
* padCharacter is the character used to fill an empty space in the field width
(3) The last step is to define the message structure at the end of the mr file.
<xml>
<group name="Transaction" maxOccurs="unbounded">
<group name="headers">
<record name="header" minOccurs="1" maxOccurs="unbounded"/>
</group>
<record name="record1" maxOccurs="unbounded"/>
<group name="footers">
<record name="footer" />
</group>
</group>
</xml>
* Each element can define the minOccurs and the maxOccurs parameter with either a 0, a positive number or
145
Channels
'unbounded'.
* Records defined in the records simplesect can only appear once in the message structure.
* Records can be grouped using the group element. The name of the group is mandatory.
* Records in a group should be ordered in the same way they appeared at the message.
Sample multirecord fixed-length message
HH00123 AB
HH00045 CDE
R1one 100
R1two 101
R1four 103
FF3
Sample multirecord definition file
<multirecord name="mymultirecord" type="fixed-length" recordDelimiter="\r\n" quoteSymbol-character="&q
<records>
<record name="header">
<field name="recordType" value="HH" width="2"/>
<field name="header1" width="5" justify="right" padCharacter="0" />
<field name="header2" width="4" justify="right" padCharacter=" " />
</record>
<record name="record1">
<field name="recordType" value="R1" width="2"/>
<field name="field1" width="5" label="My field" description="My field Descritpion" />
</record>
<record name="footer">
<field name="recordType" value="FF" width="2" />
<field name="footer1" width="1"/>
</record>
</records>
<xml>
<group name="Transaction" maxOccurs="unbounded">
<group name="headers">
<record name="header" minOccurs="1" maxOccurs="unbounded"/>
</group>
<record name="record1" maxOccurs="unbounded"/>
<group name="footers">
<record name="footer" />
</group>
</group>
</xml>
</multirecord>
Output Charset
Output charset to use to encode the file.
Input Charset
Input charset to use to decode the file.
MultiRecord definition
The MultiRecord definition file.
146
Channels
ServingXml (Visible only for Babelway admins)
The ServingXml code generated based on the Multirecord defintion file.
Sample
An example of Multirecord file handled by this message definition.
Flat File Message Format
File sample
Below is a sample Flat file.
EE54001340000093012918100700000000000147521
DD0000018713906060109 6011
DD0000028713906061106 6111
3005330101
3005250201
Output Charset
Charset to use to encode the file
Input Charset
Charset to use to decode the file
XSD
Xsd definition file corresponding to the XML message.
ServingXml
The ServingXml code file.
Sample
An example of FLATFILE handled by this message definition.
TRADACOM Message Format
TRADACOM is an early standard for EDI (Electronic Data Interchange) primarily used in the UK retail sector.
It was introduced in 1982 as an implementation of the UN/GTDI syntax, one of the precursors of EDIFACT,
and was maintained and extended by the UK Article Numbering Association (now called GS1 UK).
As Babelway supports all TRADACOM transaction sets of the TRADACOM standard, you can use any of
them in your own gateway setup.
Babelway supports all following TRADACOM documents:
1.ACKHDR, ACKMNT, ACKTLR, AVLDET, AVLHDR, AVLTLR, CORDER, CORHDR, CORTLR,
CRAHDR, CRAINF, CRATLR, CREDIT, CREHDR, CRETLR, CUSHDR, CUSINF, CUSTLR, DELHDR,
DELIVR, DELTLR, DLCDET, DLCHDR, DLCTLR, DRAHDR, DRAINF, DRATLR, EXCHDR, EXCINF,
EXCTLR, GENHDR, GENRAL, GENTLR, INVFIL, INVOIC, INVTLR, LPRDET, LPRHDR, LPRTLR, ORDERS, ORDHDR, ORDTLR, PAYHDR, PAYINF, PAYTLR, PICHDR, PICKER, PICTLR, PPRDET,
PPRHDR, PPRTLR, PRIHDR, PRIINF, PRITLR, PROHDR, PROINF, PROINF, PROTLR, RSGRSG, SADDET, SADHDR, SADTLR, SNPHDR, SNPHDR, SNPSTS, SNPTLR, SRMHDR, SRMINF, SRMTLR,
UCNDET, UCNHDR, UCNTLR, UCNTLR, UPLHDR, UPLIFT, UPLTLR, UTLBIL, UTLHDR, UTLTLR,
UVATLR, VATTLR
147
Channels
File sample
Below is a sample TRADACOM invoice file.
STX=ANAA:1+501xxxxxxxxxx:name+501xxxxxxxxxx:NAME SERVICES (U.K.)LTD.+040316:184411+00001++INVTES'
MHD=1+INVFIL:9'
TYP=0700+INVOICES'
SDT=501xxxxxxxxxx:053752CF01STDD+Tenprl Fnsrjnl Sbbqfreivpr+221 UvyyunyyRoad:Yvfohea:Co. Antrim:N.Irel
CDT=501xxxxxxxxx+NAMESERVICES (U.K.) LTD.+Cnexynaqf Pbheg:OvezvatunzTerng Cnex:Ehorel:Birmingham:OG45
FIL=1+1+040316'
FDT=040302+040302'
MTR=7'
MHD=2+INVOIC:9'
CLO=0000000100007: ++PNEEVPX GOLF CLUB:ABEGU ROAD:PNEEVPX SRETHF::OG388YC'
IRF=01000589M+040302+040302'
ODD=1+::040302+:040302'
ILD=1+1+:8408++:31266+0+2:2500:KG+54300+135800+Z+0+++SILVERSIDE 1-5 KG'
STL=1+Z+0+0+1358+++++1358++0+0++1358'
TLR=1+1358+++++1358++1358+0++1358'
MTR=8'
MHD=3+VATTLR:9'
VRS=1+Z+0+1358+1358+0+1358+1358'
MTR=3'
MHD=4+INVTLR:9'
TOT=1358+1358+0+1358+1358+1'
MTR=3'
MHD=5+RSGRSG:2'
RSG=00001+501xxxxxxxxxx'
MTR=3'
END=5'
Output Charset
Input Charset
Sample
An example of TRADACOM file handled by this message definition.
JSON Message Format
JSON Wizard screen allows you to define your JSON message format according to your own file format.
JSON (JavaScript Object Notation) is a lightweight text-based open standard designed for human-readable data
interchange. It is derived from the JavaScript scripting language for representing simple data structures and associative arrays, called objects. Despite its relationship to JavaScript, it is language-independent, with parsers
available for many languages. The JSON format is often used for serializing and transmitting structured data
for web applications.
Sample
An example of JSON file handled by this message definition.
To define a message in JSON format, select an existing template or make a copy of the generic JSON wizard in
148
Channels
the catalogue and following screen will be displayed.
File sample
Below is a sample JSON file.
{
"id": "0001",
"type": "donut",
"name": "Cake",
"ppu": 0.55,
"batters":
{
"batter":
[
{
{
{
{
"id":
"id":
"id":
"id":
"1001",
"1002",
"1003",
"1004",
"type":
"type":
"type":
"type":
"Regular" },
"Chocolate" },
"Blueberry" },
"Devil's Food" }
]
},
"topping":
[
{
{
{
{
{
{
{
"id":
"id":
"id":
"id":
"id":
"id":
"id":
"5001",
"5002",
"5005",
"5007",
"5006",
"5003",
"5004",
"type":
"type":
"type":
"type":
"type":
"type":
"type":
"None" },
"Glazed" },
"Sugar" },
"Powdered Sugar" },
"Chocolate with Sprinkles" },
"Chocolate" },
"Maple" }
]
}
Rest Message Format
REST message definition allows you to define easily a typical response for a REST request. The main particularity of this message definition is that it can generate json, xml or csv responses based on the request. This allows to define easily rest apis that supports the 3 formats with just one channel.
The output format (json, xml or csv) will be chosen according to the metadata rest_output_format. Note that
this metadata is automatically set if you use a REST Gateway IN in your channel.
CSV delimiter character
When generating csvs, the character that is used to separate the fields.
Quote character
When generating csvs, the character that is used to quote the specials character.
Headers
Tells if the csv files must begin with a line that contains headers of the columns.
So that they can be used in any output format, there are some limitations about the message definition tree that
you can use:
149
Channels
• Only the first two levels of the tree will be used when asking for csv output format. If the tree has at least 2
levels (besides the root node), the first level tags will be mapped into lines of the csv, and the second level
into columns. If the tree has only one level, fields will be mapped to columns.
• If you use a csv with headers, headers will be automatically calculated based on the element names of the
first row.
Here is an example of an output file in the 3 formats:
<root>
<country><code>BE</code><name>Belgium</name></country>
<country><code>FR</code><name>France</name></country>
</root>
[
"country" : {
"code" : "BE",
"name" : "Belgium"
},
"country" : {
"code" : "FR",
"name" : "France"
}
]
code,name
BE,Belgium
FR,France
SAP IDOC Message Format
SAP IDOC are the well-known SAP interchange formats. You can obtain the definition parser directly from
SAP. In order to do this, select the transaction WE63. Select Basic type or Extended Type according IDoc extensions usage.
IDOC parser sample
Below is a sample SAP IDOC file.
BEGIN_RECORD_SECTION
BEGIN_CONTROL_RECORD
BEGIN_FIELDS
NAME
TEXT
TYPE
LENGTH
FIELD_POS
CHARACTER_FIRST
CHARACTER_LAST
TABNAM
Name of external structure
CHARACTER
000010
0001
000001
000010
NAME
TEXT
TYPE
LENGTH
FIELD_POS
CHARACTER_FIRST
CHARACTER_LAST
MANDT
Client
CHARACTER
000003
0002
000011
000013
NAME
DOCNUM
150
Channels
TEXT
TYPE
LENGTH
FIELD_POS
CHARACTER_FIRST
CHARACTER_LAST
IDoc number
CHARACTER
000016
0003
000014
000029
NAME
DOCREL
...
Idoc parser
The Idoc parser.
Output Charset
Input Charset
Sample
An example of SAP IDOC file handled by this message definition.
Not Defined Message Format
Not Defined message format is used when in and out message format does not need to be defined because no
processing will be performed on it and no change is required.
(For format not natively supported by Babelway): Advanced users have the option to upload programmatic
code that provides support to proprietary message formats, such as specific binary ERP format (for example
idoc of SAP...)
If message in format is "Not defined", so should be the message out. Otherwise output may return unexpected
results or an empty message.
Usually, this setting is used in combination with No Transformation in a channel that simply transfers an unchanged and unprocessed message from one gateway to another different one.
Output Character Set
Charset to use to encode the file. Leave empty to keep the file as is.
Input Character Set
Charset to use to decode the file. Leave empty to keep the file as is.
Generic Message Format
Generic Wizard screen allows you to define your generic message format according to your own file format.
Output Charset
151
Channels
Input Charset
ConverterClass
The ConverterClass that is used to parse the file.
Sample
An example of the file handled by this message definition.
UBL
OASIS Universal Business Language (UBL) is the product of an international effort to define a royalty-free library of standard electronic XML business documents such as purchase orders and invoices.
File sample
Below is a sample UBL file.
<Catalogue xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2" xmlns:
<cbc:UBLVersionID>2.1</cbc:UBLVersionID>
<cbc:CustomizationID>urn:www.cenbii.eu:transaction:biicoretrdm019:ver2.0:extended:urn:www.pepp
<cbc:ProfileID>urn:www.cenbii.eu:profile:bii01:ver2.0</cbc:ProfileID>
<cbc:ID>1234</cbc:ID>
<cbc:ActionCode listID="ACTIONCODE:PEPPOL">Add</cbc:ActionCode>
<cbc:Name>Peppol Catalogue</cbc:Name>
<cbc:IssueDate>2013-08-01</cbc:IssueDate>
<cbc:VersionID>1</cbc:VersionID>
<cac:ValidityPeriod>
<cbc:StartDate>2013-09-01</cbc:StartDate>
<cbc:EndDate>2014-12-31</cbc:EndDate>
</cac:ValidityPeriod>
<cac:ReferencedContract>
<cbc:ID>3299-8RA</cbc:ID>
<cbc:ContractType>Framework</cbc:ContractType>
</cac:ReferencedContract>
<cac:ProviderParty>
<cac:PartyIdentification>
<cbc:ID schemeID="GLN">579000123002</cbc:ID>
</cac:PartyIdentification>
<cac:PartyName>
<cbc:Name>Office AS</cbc:Name>
</cac:PartyName>
</cac:ProviderParty>
<cac:ReceiverParty>
<cbc:EndpointID schemeID="NO:ORGNR">99156827</cbc:EndpointID>
<cac:PartyIdentification>
<cbc:ID schemeID="NO:ORGNR">99572527</cbc:ID>
</cac:PartyIdentification>
<cac:PartyName>
<cbc:Name>DIFI</cbc:Name>
</cac:PartyName>
</cac:ReceiverParty>
<cac:CatalogueLine>
<cbc:ID>1</cbc:ID>
<cbc:ActionCode listID="ACTIONCODE:BII2">Add</cbc:ActionCode>
<cbc:OrderableIndicator>true</cbc:OrderableIndicator>
<cbc:OrderableUnit>BX</cbc:OrderableUnit>
<cbc:OrderQuantityIncrementNumeric>1</cbc:OrderQuantityIncrementNumeric>
<cbc:MinimumOrderQuantity>1</cbc:MinimumOrderQuantity>
<cac:RequiredItemLocationQuantity>
<cac:Price>
<cbc:PriceAmount currencyID="NOK">20.00</cbc:PriceAmount>
</cac:Price>
</cac:RequiredItemLocationQuantity>
<cac:Item>
152
Channels
<cbc:Description>Ballpoint pen comes in different colours and tip sizes</cbc:D
...
Sample
An example of valid UBL file
Sample
An example of UBL file handled by this message definition.
Document type
Type and version of the UBL document. Automatically detected from the provided sample
Profile and customization
UBL Profile and UBL customization reference used to validate the UBL document. Automatically detected
from the provided sample
Disable UBL Validation
Some business rules related to the document profile and customization are automatically validated. Click
here to disable this validation.
By using UBL message definition, you will get benefit of UBL XSD validation and schematron validation for
some of the UBL Profile and Customization (OpenPEPPOL, ePrior...)
RosettaNet
The RosettaNet standard is based on XML and defines message guidelines, interfaces for business processes,
and implementation frameworks for interactions between companies. Mostly addressed is the supply chain
area, but also manufacturing, product and material data, and service processes are within scope.
RosettaNet process type
The message definition will represent a PIP action or a RNIF signal. Please select it in the list.
Disable Rosetta net Validation
Some business rules related to the process type are automatically validated. Click here to disable this validation.
4.3.6. Common Message Definition Properties
Message Definition
This file is Babelway's internal representation of your message definition tree. You can view and modify its
contents through here for troubleshooting purposes. However, we highly recommend you use the graphical editor (tree) as this guarantees that all your changes are supported by the platform.
Validation Mode
Upon processing a message, the platform will check that it matches the description configured in your message
definition tree. The validation mode describes how strictly messages need to comply with your definition in or153
Channels
der to be processed.
By default, loose validation is selected for all new message definitions. The validation modes differ in the way
they handle unrecognized fields and loops:
Strict
• Field Values: Mandatory fields and all value restrictions configured in your message definition tree will
be checked.
• Structure: Unrecognized fields will trigger an error.
• Loops: If applicable, checks that there aren't too few or too many elements in the loop.
Loose
• Field Values: Mandatory fields and all value restrictions configured in your message definition tree will
be checked.
• Structure: Unrecognized fields will be ignored and the message will be processed.
• Loops: The number of elements in loops aren't checked.
Compatibility (Deprecated)
This mode is deprecated, please contact support for more information.
4.4. Transformations
This sections covers all sections related to transformations.
Transformations are used to convert a message in into a message out.
It contains all the rules on which fields must be mapped on which ones, including optional calculations, conversions, formatting, ...
The Babelway application supports 3 ways of defining a transformation.
• Most of transformations can be defined using Drag and Drop Transformation editor.
• Alternatively, you can write your transformation directly in standard Xslt format using Xslt Transformation
editor.
• Additionally, in some specific case when no transformation is required, you can select a No Transformation
template.
4.4.1. Transformations list
The list of transformations screen shows you all the transformations defined in your environment, even if they
are not used in any channel. From here, you can easily edit them, or create new ones.
This screen is accessible by clicking on the menu Channels, then the sub-menu Transformations
154
Channels
Name
Description
Message in
The message in used as input of the transformation.
Message out
The message in produced as output of the transformation.
Created on
Last updated on
You can click on a line to view the details of the associated transformation, or edit it. See transformation
details.
The Create transformation action button allows you to create new transformations.
4.4.2. Creation of a transformation
To create a transformation, just choose its type, and click on Create transformation
You can find all details about every type of transformation in the corresponding sections :
• Visual mapping
• Xslt mapping
• No transformation
4.4.3. Transformation detail
General
155
Channels
The general tab contains the general information of the gateway, and offers actions that act on the whole transformation.
Message IN
The message definition of the input message related to this transformation.
Message OUT
The message definition of the output message related to this transformation.
Name
Description
Id
Created On
Last Updated On
Mapping / xslt
Following of the type of the transformation, these tabs define all the rules that must be applied to convert the
message in to the message out.
See Drag and Drop Transformation for defining transformation with the visual editor.
See Xslt Transformation for defining the transformation by writing an xslt.
Related items
Associated message definitions
The message definitions related to this transformation.
Using channels
Parent
Children
Change Log
This tabs shows you all the history of changes on this gateway, and allows you to revert to a past version. For
156
Channels
more details, see the change log section.
4.4.4. Drag and Drop Transformation
Drag and Drop transformation visual editor enables to easily define the transformation between your source
message and your target message.
This transformation visual editor is divided in the following zones:
• The top bar will allow you to edit all of your formulas, when a mapping rule is selected. In other circumstances, it will just guide you with contextual help.
• The left pane displays the structure of the message in.
• The right pane displays the structure of the message out.
• At the bottom of the component, you have links for global actions (save the mapping, or run a test case).
Figure 4.66. Drag and drop transformation visual editor
Note
The editor has been optimized to use all the available space of your window. To take full profit of it,
we recommend that you maximize the size of your window, especially when you work with big message definitions.
4.4.4.1. Viewing and selecting mapping rules.
An icon (chain mark) shows you at a glance all the fields that are used in the transformation.
To see how a field is used in the transformation, you can simply click on it.
157
Channels
Click on mapped field.
If you click on a node that is already used in the transformation, the nodes involved in the transformation rule
will be clearly showed on the screen. The formula bar will show the transformation formula, and allow to edit
it. For more information about how to edit a transformation formula, see section about how to edit formulas.
Figure 4.67. Visual editor when a mapping is selected.
The lines will let you see immediately all the involved nodes, even when they are combined in a formula.
Figure 4.68. Visual editor when a mapping is selected (multiple inputs).
Click on field mapped more than once.
If you click on a field that is used in more than one mapping rule, the system will show you all the mappings
rules, and ask you to choose the one you want to edit.
158
Channels
Figure 4.69. Mapping choice.
By putting your mouse on one of the mapping lines, you see all details of the given mapping. To select it and be
able to edit it, just click on the line.
Figure 4.70. Mapping choice (highlighted).
Click on not mapped field.
If you click on a field that is not used in the mapping, you will just be notified of it, and will have the possibility to initiate a new mapping rule for this field.
Figure 4.71. Selection of not mapped field.
159
Channels
Iterate through mappings..
It is also possible to iterate through all mappings thank to the arrows at the top right of the target tree zone.
Figure 4.72. Mapping iteration.
Starting from the currently selected node in the target tree (or top of the tree is no node is selected), the right arrow will find the next mapped node, and select it. In the same way, left arrow will find and select the previous
mapped node.
4.4.4.2. Nodes mapping
You can initiate new mappings via the following methods :
Drag-and-drop
Just drag your source field to the target field. A simple mapping will be defined, that say that the target field
must be filled with the value that was in the source field. You can then update the formula : see section about
how to edit formulas. When you are dragging your source field, all compatible target fields are highlighted.
Figure 4.73. New mapping (drag-and-drop)
Formula bar
The other method is to select your target field, then start typing your formula in the formula bar (see section
about how to edit formulas ). When you need source fields in your formula, you can just drag-and-drop then in
160
Channels
the formula bar.
Figure 4.74. New mapping (via formula bar)
4.4.4.3. Edit formula
Formula bar
By default, when you just make your mappings by drag-and-dropping your source fields to the corresponding
target fields, the values are associated without any transformation. You can use the formula bar (at top of the
component) to pick formulas, that will transform the input values, or combine multiple values together.
Figure 4.75. Formula bar
For advanced users, the formula language is xpath, and you can use whatever xpath function to create your formula, even if it is not documented in the function library. The only differences to pure xpath formula are :
• You can refer to source fields by just drag-and-dropping them in the formula (a summary of the node will be
displayed).
• All the documented functions, even the extensions specific to Babelway, can be called without a namespace
prefix.
Easy Function Editor
The Easy Function Editor can help you writing your formulas. It opens in two situations :
161
Channels
• When you write a function call in the formula bar. The Easy Function Editor will open automatically, and
show you help about the function you are using.
• If you open it by clicking on the "Easy Function Editor" link, at the right of the formula bar.
In any case, the help will depend on the cursor position, and show you help about the function that is called at
this precise cursor position. You can use both the formula bar or the Easy Function Editor to write your functions and their parameters. All the changes that you make in the editor panel will be automatically (and immediately) reflected in the formula bar, and vice-versa.
When you are entering the name of a function, the formula editor will just show you all the functions in the library that match the prefix you just typed. You can select the proposal by just clicking on it. The name will be
completed in your formula, and the editor will allow you to fill the parameters. You can also use the following
keyboard shortcuts :
• Enter : to select the currently highlighted proposal.
• Down arrow : to select the next proposal.
• Up arrow : to select the previous proposal.
• Escape : hide the function editor.
Figure 4.76. Formula bar - choosing your function.
When you are filling the parameters of a function, the formula editor will show you all the documentation about
the function (description, examples, ...), and allow you to pick easily the parameters.
Figure 4.77. Formula bar - filling parameters.
Whenever possible, you will receive in the function editor additional help to be able to fill easily the function
162
Channels
parameters. In the following example, using a lookup table, the editor will allow you to select your lookup table
and its columns in dropdown, whose content depend of your environment.
Figure 4.78. Formula bar - filling parameters.
The inline help describes many functions, and will help you for picking parameters for all of them. These functions should cover most of your needs. If you should not find what you search, or if the help of a function is not
clear, do not hesitate to ask to our support ([email protected]).
163
Channels
Figure 4.79. Formula bar - functions list.
Colorization of the formulas
To ease the reading and the detection of errors in the formulas, formulas are colorized.
Figure 4.80. Colorization of the formulas
• Recognized function names are displayed in italic light blue.
• String constants are displayed in dark blue.
• Other elements of the formula are displayed in black.
Validation of your formulas
If you want to be sure that your formula's syntax is correct (a valid xpath expression), you can click the validate
icon at the end the formula bar.
164
Channels
Figure 4.81. Validate formula.
If the formula is correct, the icon will become green.
Figure 4.82. Validate formula - OK.
If not, it will become red, and a summary of the error will be made available if you put your mouse on the icon.
Figure 4.83. Validate formula - KO.
The validation is also accessible by just pressing the Enter key.
Deleting a formula
If you want to delete a formula, so that the target node is not mapped anymore, you can :
• Empty the formula.
• Click on the X icon at the end of the formula bar.
Figure 4.84. Reset formula
4.4.4.4. Understanding functions
Functions are used in formulas to calculate the wanted output starting from your input fields.
Introduction
A function is an operation that takes values as inputs (the parameters), and computes an output value (the result). Functions can be written for any calculation you can think to. They will be identified by their name, and
you have to know which parameters they expect to be able to call them.
A function can be called in a formula by just typing the function name, an opening parentheses, the parameters
(separated by commas), and a closing parentheses. You can find some examples below :
165
Channels
max(3,5) -> 5
min(3,5) -> 3
lower-case('BABELWAY') -> 'babelway'
concat('First ', 'example') -> 'First example'
string-length('Babelway') -> 8
changeDateTimeFormat('2022-01-31', 'yyyy-MM-dd', 'yyyyMMdd') -> '2022031'
Function elements
The Babelway inline help will give you immediate access to all elements that describe the function.
Figure 4.85. Function elements
1. The function name identifies the function. It is what you have to write before the opening parenthesis to call
this function.
2. The library just indicates the provenance of this method. It can be one of the following :
• XSL : This function is just standard XSL. If you know XSL, it is exactly the function that you know.
Also, every help you could find on the Internet about this function is valid.
• Babelway : This function is a Babelway-specific extension to xsl. You have to read Babelway inline help
to know about this function, or call our support if you need more info.
• User : This function have been defined by you, in the context of this mapping. You can freely update or
delete it, according to your needs.
3. The description describes what the function does, and what it is intended for.
4. The result description describes the value that is returned by the function, including its type (see following
section for more information about types).
166
Channels
5. The parameters section shows all information about the parameters of the function.
a. The name of the parameter. It is just one word that should make you understand the parameter.
b. The field for the value for this parameter. You can type the value into this field.
c. More help about the parameter. You have to select the parameter for which you want to see this help.
Help starts again with the function name.
d. Type of the parameters (see following section for more information about types), and indication if this
parameter is mandatory (the default) or not.
e. More info to help you understand this parameter, and how you have to fill it.
6. The examples show you some function calls to the function, with the result. It should clarify how the function works.
Parameter types.
In every function, the parameters and the return type are typed objects (a string, a number, ...).
The reason for this is that functions can not operate on any parameter, but have requirements on them to be able
to operate. As an example, a function that would multiply its parameters will require that the parameters are
numbers. It will be able to calculate 3*5, but not 3 * 'abc'.
The type of the parameters summarizes most of the constraints on the parameters. It will also allow to detect
immediately that the function can not work, because the parameter types are not the expected ones.
The following types are used in the functions of the mapping editor.
• String. It is the most basic type. It is just a sequence of characters, without any more constraint. When you
write a String constant into a xpath expression, you have to enclose it with single quotes. Ex : 'abc', 'string
example'. Also, all the fields coming from your source document are Strings. You can therefore just dragand-drop them when you need a String parameter.
• Integer. An integer is a number without decimals, like 2 or 17 (but not 3.5). When you write a Integer constant into a xpath expression, it must be written as is, without enclosing it with a delimiter. Ex : max(3, 5)
• Boolean. A Boolean either true or false. When you write a Boolean constant into a xpath expression, it must
be written as is, without enclosing it with a delimiter. Ex : true()
• Number. A number can contain any numeric value, like 2 or or 3.5 . The best way to get a Number value
from its representation is to use the function toNumber. Ex: toNumber('3.5'). You can also write Numbers
directly in your xpath expressions, without enclosing quotes. Ex: 3.5 .
• DateTime. A date is an instant, like '02/06/2017 13:25:17.645'. As for Dates, you can not write directly DateTime constants in a xpath expression. They can only be returned by other functions, like currentDateTime(),
or parseDateTime(representation, format)
• DateTimeFormat. A DateTimeFormat is a String that is used to represent the format of a DateTime. Besides
being a String, it must comply to the same requirements as DateFormat, that are fully described in http://docs.oracle.com/javase/6/docs/api/java/text/SimpleDateFormat.html. Some examples are 'yyyy-MM-dd
hh:mm:ss', or 'ddMMyyhhmm'.
• LookupTable. A LookupTable parameter must refer to an existing LookupTable in your environment. You
167
Channels
can write a reference to a LookupTable directly in a formula by writing a string constant containing the name
(or the id) of the lookup table ('stocks', 'clients', ...). In the Easy Function Editor, you can just choose your table in a dropdown.
• LookupTableColumn. A LookupTableColumn parameter must refer to a column of a specific LookupTable.
You can write a reference to a LookupTableColumn directly in a formula by writing a string constant containing the name (or the index) of the column ('name', 'code', ...). In the Easy Function Editor, you can just
choose your column in a dropdown.
• Node. A single xml elements. This type will be used to represent a single xml node from your source document or from an additional xml source. To fill it, you should drag-and-drop a simple node to the field or to
use a xpath expression referring to a single Node.
• NodeList. A list of xml elements. This type will be used to represent a list of nodes in your source document.
To fill it, you should drag-and-drop a loop node to the field.
• Object. Object is a special value meaning that anything is accepted. You can use Strings, Integers, Dates, ...
To illustrate the importance of types, take a deeper look to the differences between the functions changeDateTimeFormat and formatDateTime. changeDateTimeFormat will take the input date as a String. But it doesn't
contain enough information to interpret it as a DateTime. Therefore, it also takes another parameter that is the
format of this representation.
changeDateTimeFormat('2022-01-31', 'yyyy-MM-dd', 'yyyyMMdd')
formatDateTime will take the input date by just taking one DateTime parameter.
formatDateTime(currentDateTime(), 'yyyyMMdd')
formatDateTime(parseDateTime('2022-01-31', 'yyyy-MM-dd'), 'yyyyMMdd')
If you just want to change the format of a date contained in one of your source fields, changeDateTimeFormat
looks to be exactly the ideal method. But passing by the DateTime objects will just be easier (and for many
cases the only way) if you need to make more complex calculations.
formatDateTime(addDays(currentDateTime(), 7), 'yyyyMMdd')
In any case, you have to realize that following calls would just be WRONG :
formatDateTime('2022-01-31', 'yyyyMMdd')
// formatDateTime expects a DateTime as first parameter, n
changeDateTimeFormat(currentDate(), 'yyyy-MM-dd', 'yyyyMMdd')
// changeDateTimeFormat expects a St
4.4.4.5. User-defined functions
Babelway offers many functions to make the calculations in your mappings. These functions should be enough
for most of your needs. Anyway, in some situations, you could want to define additional functions, to simplify
your mappings.
Specialize existing function to specific needs
The first reason why you could want to create additional functions is to specialize existing functions to your
context.
As an example, let's suppose that you must convert in your mapping many dates, and that the input format is always ddMMyyyy or dd/MM/yyyy, and the output format must always be yyyyMMdd. In Babelway, this can be
achieved easily by using the function changeDateTimeFormat.
changeDateTimeFormat([yourField], 'ddMMyyyy,dd/MM/yyyy', 'yyyyMMdd')
168
Channels
Anyway, having to type the input and output formats in every of these formulas can be tedious, and it would be
easier to be able to write
convertDate([yourField])
This can be achieved by defining a function that suits this specific need :
convertDate(x) = changeDateTimeFormat(x, 'ddMMyyyy,dd/MM/yyyy', 'yyyyMMdd')
This scenario of specializing a method can be used in many situations : accessing a lookup table, formatting
fields, ...
stock(x) = lookupTableValue('stocks', 'productId', 'stock', x)
pad(x) = padLeft(x, 20, ' ')
Simplify complex formulas
Another situation where user functions are useful is when you have to write very complex (or long) formulas.
Defining functions can simplify greatly the writing by allowing to factorize (and name) parts of the formulas.
In the following example, defining the intermediate function nextWeekDay has greatly improved the readability of the formula.
[DeliveryDate] = formatDateTime(nextWeekDay(nextWeekDay(currentDateTime())), 'yyyyMMdd')
nextWeekDay(day) = addDays($day, IF(formatDateTime($day, 'E')='Fri', 3, IF(formatDateTime($day, 'E')='
The improvement in readability will increase with the complexity of the formula you have to write.
Definition in the interface
You have the ability to create your function from the screen with search of functions, in the function library.
Figure 4.86. Defining user function (1)
When the link is clicked, you have access to a screen that will ask you for all the details of functions.
169
Channels
All the concepts are the same as the one displayed for the already existing functions. See section about standard
functions for in-depth explanation of every field. The fields are :
1. The function name identifies the function. It is what you have to write before the opening parenthesis to call
this function.
2. The description describes what the function does, and what it is intended for. This description is not required
for user functions, but filling it will allow the interface to show you help when you use the function, as for
all the other functions.
3. The parameters section asks you for all the information about the parameters of the function.
a. The name of the parameter. It is just one word that should make you understand the parameter. It is also
with this name that you will be able to reference the parameter in the implementation of the function.
b. Type of the parameter.
c. Description of the parameter.
4. The result section asks you for the type of the result of the function (a), and a small description of this result
(b).
5. The formula is the formula that implements the function. In this formula, you can reference the function
parameters with the dollar sign ('$') followed by the name of the parameter.
Updating or deleting user functions
Starting again from the screen with list of functions, user functions have one more link to be able to edit them.
If you click on it, you will come again in the screen of the definition of the function, and you will be able to
change the function, or delete it.
170
Channels
4.4.4.6. Sub-formulas
Sub-formulas are parts of formulas, that you can name and reuse later.
Sub-formulas are another way of simplify writing of very long formulas.
• When you work on this part of the formula, you only see this part (instead of the whole formula), and do not
have to identify this part again and again inside the whole formula.
• When you work on the main formula, it is much smaller and readable, as all complex parts have been factorized and are just replaced by a reference to the sub-formula.
Sub-formulas also allow you to share common part of long formulas across different formulas. If you need to
change this part, you will only have to change it once, and all using formulas will be automatically updated.
Example
As an example, let's imagine that you have to make some complex calculations to calculate a date and time,
then put the date in one field, and the time in another field.
[DeliveryDate] = formatDateTime(addDays(parseDateTime([yourDate], 'yyyyMMddhhmm'), if ([productType]==
[DeliveryTime] = formatDateTime(addDays(parseDateTime([yourDate], 'yyyyMMddhhmm'), if ([productType]==
By using a sub-formula, you could factorize the common part, and just let the outer formulas deal with selection of date or time in complex formula.
[DeliveryDate] = formatDateTime([DeliveryDateTime], 'dd/MM/yyyy')
[DeliveryTime] = formatDateTime([DeliveryDateTime]), 'hh:mm:ss')
[DeliveryDateTime] = addDays(parseDateTime([yourDate], 'yyyyMMddhhmm'), if ([productType]==1 || [produ
The new version is much more readable. If you still find it too complex, you could even go further, and separate the calculation of [DeliveryDateTime] in 2 parts.
[DeliveryDate] = formatDateTime([DeliveryDateTime], 'dd/MM/yyyy')
[DeliveryTime] = formatDateTime([DeliveryDateTime]), 'hh:mm:ss')
[DeliveryDateTime] = addDays(parseDateTime([yourDate], 'yyyyMMddhhmm'), [DaysNeededToDeliver])
[DaysNeededToDeliver] = if ([productType]==1 || [productType]==2) then 3 else 2
Execution
171
Channels
The result of the execution of the formulas will always be exactly the same if you factorize some parts in subformulas or not. Using sub-formulas is a way of writing your formula easier, but is always completely equivalent to the fully expanded formula.
To illustrate, let's take the following complete formula, whose result will be '0 1'
concat(next-counter-value('invoice'), ' ', next-counter-value('invoice'))
If you decide to write it using a sub-formula, the result will still be exactly the same : '0 1', because nextcounter-value will still be evaluated twice, exactly like in the previous formula.
concat([mySubFormula], ' ', [mySubFormula])
[mySubFormula] = next-counter-value('invoice')
Create a sub-formula
You can find sub-formulas at the top of the output tree.
To create a new sub-formula, just open the section, click on the '...' at the bottom of the section, and choose the
name that you want to give to the sub-formula.
Figure 4.89. Create sub-formula (1)
Figure 4.90. Create sub-formula (2)
Define a sub-formula
Sub-formulas can be defined the same way as any other output field. See sections about how to map nodes, or
how to edit formulas for more details.
172
Channels
Figure 4.91. Define a sub-formula
Use a sub-formula
Sub-formulas can be used the same way as any other input field. To make this possible, all sub-formulas are
also available at the top of the tree with your incoming message. You can really see them as "virtual input
fields", or "calculated input fields".
Figure 4.92. Use a sub-formula
In your formulas, sub-formulas references can be easily recognized : they are drawn like references to input
fields, but with a purple text.
Figure 4.93. Sub-formula reference in a formula
Global overview
When you have many nested sub-formulas, or user-functions, you can always have a global overview of your
formula by using the "Copy-paste version".
173
Channels
Figure 4.94. Sub-formula global view
Delete a sub-formula
To delete a sub-formula, use the action at the right of the formula bar.
The sub-formula will be deleted, and all references to this sub-formula will be inlined, leading to the situation
you would have had by writing all your formulas without using this sub-formula.
Figure 4.95. Delete sub-formula
4.4.4.7. Working with formulas - frequent scenarios
This section explains in details some frequent scenarios, when you work with formula. It gives a lot of examples, and also emphasizes some traps in which you should not fall.
Working with numbers
When you have to do some calculations, you must always keep in mind that all fields from your source and target documents are String, not Numbers. To be able to make calculations, xpath (like any programming language) needs Numbers. If your values are String, they have to be converted first to Numbers, even is this conversion can be implicit in some cases.
Babelway recommends that you always convert explicitly your input fields with the toNumber function. As an
example, the following call will perfectly work for all values.
toNumber([yourInputField])/100
We can show some results for some input values.
toNumber('100')*0.1 -> '10'
toNumber('30507')*0.1 -> '3050.7'
When you have to convert the results of your calculations (Numbers) to Strings (as expected by the target
174
Channels
field), it is safe to use implicit conversion. The system will automatically convert your number to its more natural representation (the one without useless zeros).
toNumber('100.00')*0.100)
->
'10'
You only need to make an explicit conversion if you want to use another representation. For example, the following call will ensure that target number is always displayed with 2 decimals.
formatNumber(toNumber('100')*0.1, '0.00')
->
'10.00'
If you do not follow there recommendations, here are some problems you could encounter :
• Using xpath implicit conversions or conversions via the xpath number() function could lead to numeric problems.
number('30507')*0.1
->
'3050.7000000000003'
• Display in scientific notation.
number('1234567890')*100
->
'1.23456789E11'
In some old mappings, you could see uses of a function named bif:cast. This function was added automatically
in some cases to try to correct incorrect numbers, having the problems as described in this section. You should
just check (or change) the formula so that it follows the recommendations of this section, and remove all the
calls to bif:cast.
Also, bif:cast has just no effect when its argument was not a Number, and it can be removed safely in all of
these situations.
Changing date format
If you receive in your input document dates/times in one format, and want to write them in the output document
in another format, it can be easily achieved using the changeDateTimeFormat function.
changeDateTimeFormat([yourInputField], [yourInputFormat], [yourOutputFormat])
All
details
about
the
date
formats
can
tp://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html.
be
found
on
ht-
Some examples :
changeDateTimeFormat('01/01/2015', 'dd/MM/yyyy', 'yyyyMMdd') -> '20150101'
changeDateTimeFormat('01/01/2015 12:34:56', 'dd/MM/yyyy hh:mm:ss', 'yyyyMMddhhmmss') -> '201501011234
changeDateTimeFormat('01/01/2015 12:34:56', 'dd/MM/yyyy hh:mm:ss', 'dd-MM-yyyy') -> '01-01-2015'
changeDateTimeFormat('30/02/2015', 'dd/MM/yyyy', 'dd-MM-yyyy') -> Error
This function can also be used to extract almost any information about a DateTime
changeDateTimeFormat('01/01/2015', 'dd/MM/yyyy', 'EEEE')
-> 'Thursday'
The list of all options usable in the format parameters
tp://docs.oracle.com/javase/6/docs/api/java/text/SimpleDateFormat.html
can
be
found
on
ht-
This function will also do the job very easily if the input can be in different formats. You just have to enumer-
175
Channels
ate the possible formats, separated by a comma, in the input format.
changeDateTimeFormat('01/01/2015', 'dd/MM/yyyy,yyyyMMdd', 'yyyyMMdd') -> '20150101'
changeDateTimeFormat('20150101', 'dd/MM/yyyy,yyyyMMdd', 'yyyyMMdd') -> '20150101'
If you have many transformations to do, with always the same formats, it can help to define a more convenient
user function, to avoid having to write the formats at every call. This is explained in details in the sections
about user functions.
convertDate('01/01/2015')
-> '20150101'
Making Date/Time calculations
As for making calculations with numbers, you have to remember that fields from input and output documents
are Strings, and you will have to convert them to DateTime objects to be able to make your calculations.
You can get DateTime objects by creating them from their representation, via the parseDateTime function. You
can also receive DateTime object via some methods like currentDateTime
The conversion of a DateTime to its representation can be done via the formatDateTime function.
When you have DateTime values, there are many functions that allows to make some calculations (ex: addDays
)
formatDateTime(addDays(parseDateTime('2014-06-28', 'yyyy-MM-dd'), 4), 'yyyy-MM-dd') -> '2014-07-01'
Counter
The following techniques can be used if you need to implement a counter.
1. Xpath functions
You can use xpath formulas. Here are some examples :
• The function position() gives you the index of the iteration in the loops. It can be used to number every
row.
• Xpath functions like count(preceding-sibling::*) allow you to count position of an element within a list of
selected elements.
2. Metadata
You can define a metadata, and increment it at each call. It will return successfully values 0, 1, 2, 3, ...
You can use the function nextCounterValue(counterName) to do all the job for you. It will increment the
value of the metadata by 1, and return the new value.
3. Lookup table
The two previous techniques are simple, but will only work inside a given message. They will not work
across multiple messages. If you need to implement a persistent counter, you can work with a lookup table :
• Create a lookup table named 'counters' with two columns named 'name, value'.
• Add an entry (mycounter, 0).
176
Channels
• In your mapping, use the function incrementLookupTableValue('counters', 'name', 'value', 'mycounter'). It
will automatically increment the value, and return the new value.
Getting Information From An External HTTP Ressource
Babelway offers specialized transformation functions to call external web services. This is be useful to complement the message data and lookup tables with external source of information.
You can reach HTTP ressources using one of the following 3 functions: httpGet, httpPost or httpSoap. You will
get a string representation of the response. Moreover, these function can be associated with xmlToXmlNode or
jsonToXmlNode to get a usable tree representation of the response that can be directly used in other Xpath
functions.
upper-case(jsonToXmlNode(httpGet(concat('http://www.telize.com/geoip/', IP)))//*:country) -> BELGIUM
Figure 4.96. Calling HTTP ressource
Please note that Xpath expression selecting node in the resulting tree needs handle namespaces by adding a *:
in front of the xml nome of the node, like *:country in the example above. You need to do this even if the resulting tree is not part of a namespace, like in Json processing.
Storing Json or Xml in a lookup table
Lookup tables are very versatiles, they can hold up to 10 columns. Stored data can be simple but they can also
be structured in Json or in Xml. This feature, in combination with the power of Xpath offers you endless possibilities to store and retrieve the data you need.
The best practice is to use one column for each data you want to search on. That makes up to 9 indexes and the
last column to store the Xml or Json.
177
Channels
Figure 4.97. Xml in lookup table
You can use a the 'Create data import channel' button of your lookup table to help you importing your data.
Take a look at the xmlNodeToXml function. It will help you serializing a piece of your Xml before you store it
in the content column.
xmlNodeToXml(Country) -> <Country><Code>BE</Code><Population>11008000</Population><Area>30507</Area><N
Figure 4.98. Import Xml in lookup table
Once the Xml or the Json is retrieved from the lookup table, it can be parsed with one of the following functions xmlToXmlNode or jsonToXmlNode to get a usable tree representation directly usable in other Xpath
functions.
xmlToXmlNode(lookupTableValue('testXML', 'ip', 'xml', key))//*:country -> BELGIUM
178
Channels
Figure 4.99. Use Xml from lookup table
Please note that Xpath expression selecting node in the resulting tree needs handle namespaces by adding a *:
in front of the xml nome of the node, like *:country in the example above. You need to do this even if the resulting tree is not part of a namespace, like in Json processing.
4.4.4.8. Mapping loops
Loops from the input message must be mapped to the output if you want to map one of its enclosed fields. Otherwise the mapper cannot resolve the reference to the field since there can be more than one occurrence. The
"loop mappings" tell the mapper how to deal with this multiplicity of values.
You can make loop mappings to loop or value fields.
Loop to loop
In this case, every occurence of the source loop will by default lead to the creation of an occurence of the target
loop.
It is possible to change the source loop (sort, filter, ...) by just adding a formula on it. The most used functions
in this context are :
• sortLoop : This function will sort the source loop according to a given criteria. Example : sortLoop([Loop],
'Code') will sort the loop elements following the value of their field Code.
• sortLoopNumeric : This function will sort the source loop according to a given numeric criteria
• filterLoop : This function will filter the source loop, and only keep elements that match the given condition.
Example filterLoop([Loop], 'Area>30000') will only keep the elements for which the field Area contains a
value greater than 300000
You can find here a complete example, with sort and filter. The loop mapping only keeps countries with an
Area>300000, and sort the loop items according to the Code field. Example file and how it is mapped is also
shown.
179
Channels
Figure 4.100. Loop to loop mapping with filter and sort.
Loop to value
In this case, only one occurence of the loop will be used, as the target field doesn't allow repetition of value.
By default, the first occurence of the loop is used, but you can again change the default by using a formula. If
your formula still returns a list of elements, only the first one will be used.
Note that if the source loop is empty, an empty element will be created in the out message.
You can find here a complete example, that chooses the Country with the biggest Area value. The sortLoop call
will sort the list in decreasing order of Area. As this result still contains multiple entries, the first one will be
automatically selected.
180
Channels
Figure 4.101. Loop to node mapping with sort.
Identify loop mappings in the interface
Loop mappings are identified with an additional icon in the formula bar.
Figure 4.102. Identifying loop mappings
Loop instructions without this icon will not work !
You can initiate a loop mapping by dragging a (input) loop to a target node. Directly selecting target node, and
typing formula in the formula bar will only lead to creation of value mappings, not loop mappings.
Writing xpath expressions in loop functions
All the loop functions (filterLoop, sortLoop, ...) take as second parameter a String, that will be interpreted as an
xpath. This xpath will be evaluated for every element of the list, to calculate the value that will be used to sort
181
Channels
or filter.
The current node for the evaluation of this xpath will be the node of the list itself, and you can refer it with '.'.
As an example, an expression like 'Code' is completely equivalent to './Code', and refers to the xml element
Code, that is a direct child of the element on which the loop applies. On the previous examples, references like
'Code' or 'Area' in the xpath work, because these names are the names of the xml elements that are direct children of the element on which the loop applies (Country).
You must also be careful of always using the names of the fields to reference them in xpath, and not the labels.
Labels are just present in the interface to be clearer, but do not correspond to anything in xpath or xml. This
case happens more often when using csv messages, where all the fields will have the same name ('field'), even
if they can have different labels ('Name', 'Code', 'Area', ...). In this case, an xpath like 'Code' will not correspond
to anything, but you may for example use a reference like 'field[2]' .
As the second parameter (the xpath) is a String, and that Strings are delimited by single quotes, writing a xpath
expression that also uses single quotes can also be a little tedious: you have to double your single quotes. As an
example, the expression to filter Countries to only keep the one with Code='BE' will be
filterLoop([Loop], 'Code=''BE''')
Figure 4.103. Writing a filterLoop with a quote in the condition.
If you type your expression in the EasyFunctionEditor instead of the formula bar, you can type your expression
normally, and the editor will make the necessary quotings for you.
Figure 4.104. Writing same filterLoop using the EasyFunctionEditor.
4.4.4.9. Multi nodes mapping
182
Channels
Visual mapping is able to map two message definition tree structures, when they have the same fields. This is a
very valuable when dealing with complex and often similar XML messages like in soap messages, IDOC or
UBL...
To map the 2 structures, drag-and-drop your source structure to the target structure. As you can see in the
screenshot, structure nodes can only be mapped on other structure nodes, not on fields.
Figure 4.105. Structure mapping - drag-and-drop
Confirm the operation.
Figure 4.106. Structure mapping - confirmation
As you can see, all the corresponding nodes have been mapped.
Figure 4.107. Structure mapping - result
183
Channels
The multi-nodes mapping will work even if there are additional nodes in one of the 2 structures. These nodes
will be ignored.
But the multi-nodes mapping will ignore nodes that are present multiple times in the structure. Example, if your
node Country contains 2 different children named Code, no mapping will be made for fields Code, because it is
not clear for the system what is the correct association.
4.4.4.10. Using or changing metadata
In drag and drop transformation you can use metadata associated with the incoming message (such as fileName, receive date, ...). You can also store whatever info in a metadata for future use.
Using metadata
Accessing metadata can be done in your formulas with the function metadata. It just takes one argument, that is
the name of the metadata.
Figure 4.108. Using metadata
Define metadata
Defining your own metadata, and storing values into them can be done via the metadata section, on top of the
target tree.
To add a new metadata, click on last entry ('...'), and choose your name.
Once the metadata defined, you can just map value to it exactly as for other fields.
184
Channels
Figure 4.109. Using metadata
Working with object metadata
Babelway transformation supports working with object metadata. This is very useful to add a PDF or images
extracted using a Zip unwrapping extra processing in a XML as a Base64 string.
Figure 4.110. Object metadata as base64
4.4.4.11. Drag and Drop transformation properties
The following properties are available :
Mapping definition
This file is the definition of the visual mapping. You normally edit it via the mapping tree editor.
Xslt
This file is the xslt transformation that will be applied on the internal xml representation of your incoming
message to transform it into the outgoing message. It is generated from the mapping definition file.
You can only edit this file via the mapping definition file. If you want to write directly advanced xslt transformation, you have to use a xslt transformation instead of a visual transformation.
Xslt includes
Xslt files that will be included in the generated xslt. It allows you to define some custom xslt functions, and
185
Channels
use them in the mapping. The uploaded file must contain all of your functions. It must looks like :
<xsl:stylesheet version="2.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:bfn="http://xmlns.babelway.com/2007/function"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:common="http://exslt.org/common"
xmlns:math="http://exslt.org/math"
xmlns:sets="http://exslt.org/sets"
xmlns:dates-and-times="http://exslt.org/dates-and-times"
xmlns:random="http://exslt.org/random"
xmlns:saxon="http://saxon.sf.net/"
>
<xsl:function name="bfn:xml-parse" >
<xsl:param name="xmlString"/>
<xsl:sequence select="saxon:parse($xmlString)"/>
</xsl:function>
</xsl:stylesheet>
Transformation mode
Allows you to use special transformation modes. the available modes are :
• Normal : transformation reads content and metadata of the incoming message, and its result will affect
content and metadata of the outgoing message.
• Metadata only for outgoing message : only the metadata of the outgoing message will be updated. The
content of the outgoing message wil be the same is the input. This mode can be used in special situations
where the transformation must only generate some additional metadata.
• Metadata only for incoming message : only the metadata of the incoming message will be used, not its
content. This mode can be used in special situations where the transformation only operated on the
metadata of the incoming message. A dummy message in will be used instead of the incoming content.
• Metadata only : the transformation only operates on the metadata of the incoming message, and can only
update metadata of the outgoing message. Content will not be updated by the transform.
4.4.5. Xslt Transformation
Xslt transformation test editor enables to define transformation rules and implement transformation functions
directly in Xslt language.
When specifying transformation for the first time or when changing transformation type, click on Open catalogue command and choose an Xslt transformation from catalogue. Please refer to The Catalogue chapter for
more informations about catalogue use and commands.
If you create a copy from a Babelway template you must name this copy before accessing the text editor screen.
Xslt mapping and transformation rules can be entered directly using integrated Xslt editor as illustrated hereunder.
186
Channels
Figure 4.111. Xslt transformation editor
Once all your mapping and transformations are ready and additional filter, if and/or format entered, do not forget to save this transformation with Save button.
The following (advanced) properties exist for xslt transforms.
Xslt
the xslt of the transform. It is the same xslt that can be used via the graphical editor/
Transformation mode
Allows you to use special transformation modes. the available modes are :
• Normal : transformation reads content and metadata of the incoming message, and its result will affect
content and metadata of the outgoing message.
• Metadata only for outgoing message : only the metadata of the outgoing message will be updated. The
content of the outgoing message wil be the same is the input. This mode can be used in special situations
where the transformation must only generate some additional metadata.
• Metadata only for incoming message : only the metadata of the incoming message will be used, not its
content. This mode can be used in special situations where the transformation only operated on the
metadata of the incoming message. A dummy message in will be used instead of the incoming content.
• Metadata only : the transformation only operates on the metadata of the incoming message, and can only
update metadata of the outgoing message. Content will not be updated by the transform.
4.4.6. No Transformation
The No transformation option is used when Babelway interface is used to transfer an unchanged message from
one gateway to another.
If you are only transfering messages that do not require transformation from one gateway to another one, for
example from a mail server to an FTP serve, you should use the "No transformation" transformation.
When specifying this transformation for the first time or when changing transformation type, click on Open
catalogue command and choose an No transformation transformation from catalogue. Please refer to Catalogue chapter for more informations about catalogue use and commands.
Note
187
Channels
If message in and out formats are not the same, using this no transformation setting may return unexpected results or empty out message.
Usually, this setting is used in combination with in and out Not Defined Message Formats in a channel
that simply transfers an unchanged and unprocessed message from one gateway to another different
one.
4.5. Notifications
This section contains all the stuff needed to manage your notifications. A simplified edition of the notifications
is directly available in the channels overview, but you need to come to this section to have access to all functionnalities.
Message notifications allows you to be informed by email when a message is processed by the Babelway platform. You can choose to be notified upon :
• Success: You are notified when message processing is fully completed, and is successful (when message
status is changed to Success).
• Failure: You are notified when the processing of a message has failed (when message status is changed to Error).
• File available: You are notified when the output message is available. For client gateways, where we have to
push the message to a remote server, the notification condition is the same as the Success condition. For
server gateways, when we have to make the file available on a Babelway server, where you will be able to
download it, the "File available" notification will be sent when the file is available for download on Babelway server (allowing you to know that you have to come and download it), while the "Success" notification
will only be sent when you have successfully received the file (after the download).
A special notification, named Alert notification also allows you to be informed by email when an alert is generated by the Babelway platform. This notification can not be deleted.
You can configure notifications in details : recipients in case of error, recipients in case of success, texts, ...
As for all other elements, notifications can be managed centrally, and reused in many channels.
4.5.1. Notifications list
The List of Notifications screen shows you all the notifications defined in your environment, even if they are
not used in any channel. From here, you can easily edit them, or create new ones.
This screen is accessible by clicking on the menu Channels, then the sub-menu Notifications
188
Channels
Figure 4.112. Notifications list screen
Name
A name that identifies the notification.
Description
A free description for the notification.
Success Recipients
A comma-separated list of emails to which a notification will be sent when a message has been successfully
processed.
Failure Recipients
A comma-separated list of emails to which a notification will be sent every time the processing of a message fails.
File available Recipients
A comma-separated list of emails to which a notification will be sent when messageOut is available. See
notifications main section for precise conditions when each notification is sent.
Id
A technical identifier for the notification.
Created on
Last updated on
You can click on a line to view the details of the associated notification, or edit it. See notification details.
The Create notification action button allows you to create a new notification.
The Clean notifications action button allows you to very easily delete all the notifications that are not used. The
interface will just show you the list of all notifications that are deletable (this mean not used in any channel).
You'll just have to tick the ones that you want to be deleted, and confirm the operation.
4.5.2. Notification detail
This page shows all the details about a notification, and gives access to all operations that can be made in notifications.
This page can be accessed from the notifications list, the Notifications tab of the channels detail page, or by following any link that refers to a notification.
The page contains the following tabs:
General
189
Channels
The general tab contains the signaletic information of the notification, and offers actions that act on the whole
notification.
Name
Description
Id
Created On
Last Updated On
The Save action button allows you to save the changes that you have made in this tab (name and description).
The Delete action button allows you to delete the notification, but it is only accessible if the notification is not
used in any channel.
Figure 4.113. Notification detail - tab General
Recipients
This tab allows you to configure to who the notification emails will be sent.
Target users
This table allows you to choose who will receive the notification, amongst all the users that can access the
environment.
Additional emails
This table allows you to add other email addresses, to which notifications will also be sent.
For email addresses of your users, we recommend that you select them in "Target users", and not add them
here. The advantage of placing them in "Target users" is that their email will be automatically updated
190
Channels
when you change the signaletic of the user in the admin section, or the user will be automatically removed
from the notification if you remove the access to your environment to this user.
To add an email to this list, just add the email in the input field in the last line of the table, and save. Emails
are automatically removed if you untick all checkboxes in a line.
Target gateways
This table allows you to choose what Internal gateway In will receive in the notification, amonst all the internal gateway is defined in the environment.
Note that selecting a inactive gateway (not deployed in production) will prevent the environment to deploy.
Figure 4.114. Notification detail - tab Recipients
Email
This tab allows you to configure the content of notification emails, for every type of notification. See notifications main section for precise conditions when each notification sent.
Sender
The email address 'from' of all the notification emails.
Success subject
The subject of notification emails, for "Success" notifications.
Success body
The body of notification emails,for "Success" notifications.
Failure subject
The subject of notification emails, for "Failure" notifications.
Failure body
The body of notification emails, for "Failure" notifications.
File available subject
191
Channels
The subject of notification emails, for "File available" notifications.
File available body
The body of notification emails,for "File available" notifications.
These subject and body fields are free text fields that you can fill in as you want. In addition you can use
Metadata to customize your messages adding dynamic information such as message name, account environment and channel identification, time and type of error...
Figure 4.115. Notification detail - tab Email
Related items
Using channels
192
Channels
Connected gateways
List of gateways to which this notification sends messages.
Figure 4.116. Notification detail - tab Related items
4.6. Partners
The Partners are the entities that communicate via Babelway.
For example, when Babelway is used to tranfer an invoice from Coca-Cola to Colruyt, the 2 partners involved
in the communication are Coca-Cola and Colruyt. Coca-Cola is the sender, or Partner IN. Colruyt is the receiver, or Partner OUT.
Babelway allows you to :
• Define and manage your partners, including additional infos like a description, contact information, address,
... and every other information (specific to you) that you want to store with your partners.
• Assign automatically partners to the messages processed in your environment.
• Extract partner infos directly from the messages processed in your environment.
• Make searchs, or get statistics based on your partner (ex: give me all the invoices sent to Colruyt).
• Be compliant to GS1.
Partners and gateways are different concepts. The Partners is really the entity involved in the communication
(typically a company), while Gateways represent a technical way of reaching this partner (eg "send an email to
address [email protected]", or "Place files on ftp server of mypartner.com").
You can have multiple gateways to connect to the same partner (ex: invoices must be sent by email, while orders must be sent via ftp).
A simple gateway can also be used to communicate with multiple partners. For example, I could setup an Email
gateway IN [email protected], that all of my clients are allowed to use to send me an order. In this case,
the sender (partner IN) will just be written in the order.
4.6.1. Defining partners manually
To define your partners, the easiest way is to go to the Partners section. As for all sections, you will first come
to a main screen with the list of all your partners.
193
Channels
Figure 4.117. Partners section
The action button Create Partner, at the bottom of the list allows you to define new partners. You just have to
fill the different information. As for all other objectives, you can also use the Reuse and save time zone, at the
right of the screen, to easily import partners already defined in the Babelway catalogue. See section Reuse and
save time section for more details.
Figure 4.118. Partner creation
The identifiers that you assign to this partner are quite important, as they will be used to identify the partners of
your messages. For example, when an order will be processed, the system will see that the sender of the order is
the company with TVA BE XXX. It will deduce your partner (and make the link) by finding which partner you
have assigned this TVA number to. For this reason, you can not have two different partners with the same identifier. See section Assigning partners to messages for more details.
It is up to you to organize your partners as you want. The best way is to make them really like you think, en194
Channels
coding how your relationship with your clients happens. Some people may for example want to have two different partners for "Carrefour Belgium" and for "Carrefour France", while another is not interested by the distinction and just wants a single partner "Carrefour". A third one could prefer different partners for every supermarket ("Carrefour Wavre", "Carrefour Bruxelles", ...). You can choose the solution that best fits your needs.
To do so, you just have to list all the ids (TVA, GLN, ...) of all the companies that you want to group into this
partner.
All the other fields are quite informative, and you can use them freely to store and retrieve your main information about the partner.
If you want to store other data for your partners, you can add your own fields in the Environment settings.
These custom fields wil be available in the edition of the partners, or in the list, as for the standrad fields.
Figure 4.119. Edition of partner with user fields.
Figure 4.120. List of partners with user fields.
195
Channels
4.6.2. Assigning partners to messages
Assigning partners to the messages automatically is interesting, because it will allow you to view the directly
partners involved in a message, make search egs.("give me all messages exchanged with partner X") or make
stats by partners, ... See section Using partners for more details.
You can associate two partners with messages:
• The Partner IN. It is the entity from which the message comes, the sender of the message.
• The Partner OUT. It is the entity to which the message is adressed, the recipient of the message.
Figure 4.121. Partners IN and OUT in list of messages
Assigning partners via gateways
The easiest way to assign partners to messages is to tell the system "All the messages that are processed by this
gateway come from partner X", or "All the messages that are processed by this gateway go to partner Y".
This is the easiest way, when a specific gateway is only used to communicate with ONE partner.
To make this in the interface, you have to go to the GatewayDetail screen, in the General tab, and just choose
your partner. You have to define your partners first, so that you can choose it from the dropdown menu.
Figure 4.122. Assigning partners via gateways
196
Channels
Assigning partners via MessageDefinitions
The previous case was very easy, but is not possible when your gateway is used to communicate to multiple
partners. For example, if you setup an email Gateway IN to receive orders from all of your clients, you can not
associate this gateway to just one partner.
In this case, the only way to known the sender of the order is to open the order, and read the sender in it.
To do this in the interface, you have to go to the definition of the structure of the MessageDefinition, select the
fields that contains the ids of the partners (VAT, GLN, ...), and set this info in the "Semantic field" zone.
Figure 4.123. Assigning partners via MessageDefinitions
To identify partners, you just need to designate one field with one id for the partner IN, and one field with one
id for the partner OUT. Anyway, the interface also allows you to flag other fields to tell the system what they
contain, like the name, or the address of the partners IN and OUT. This info are not needed to identify partners
(ids are enough), but it can be interesting to fill them, as they can then be used to create your partners automatically from the data contained in your messages. See section Create your partners from messages for more details.
197
Channels
Figure 4.124. Designating other fields in MessageDefinition
Note
As for all other elements of the application, the changes will only apply after deployment of your environment. Changes in partners (add, delete, change of ids, ...) also need to be deployed to apply to production messages.
Conflicts during identification
There are four steps of the processing of the message where partners can be identified: gatewayIn step (for partner IN), messageDefinitionIn step (IN and OUT), messageDefinitionOut step (IN and OUT) and gatewayOut
step (OUT).
If you fill the partner info in just one of these steps, it will be enough for the system to extract the information.
Filling the information in many of these steps should not cause any problem, as the extracted info should be the
same as each step. For example, there is no reason (apart from wrong configuration), when ids of the sender
would be different in the source format of the message than in the output format of the message.
Anyway, if it should happen, the message will not be set in error, and the first identified partner will be assigned to your message. A warning will also be added to the execution log of the message.
Figure 4.125. Message processing log - partner identification conflict
4.6.3. Creating your partners from messages
It is also possible to automatically analyse a set of messages to extract/create your selected partners.
The procedure is the following:
• Verify that you have told the system which fields of your messages contains the partner information.
• Select the messages that you want to analyze, and click on Extract partners from these messages
198
Channels
Figure 4.126. Extract partners from messages - messages selection
• Confirm
Figure 4.127. Extract partners from messages - confirmation
• The system will extract all possible partners, and show you found informations. Select the partners you want
to create, and click on Create selected partners
Figure 4.128. Extract partners from messages - select partners to create
Figure 4.129. Extract partners from messages - Confirmation of creation
199
Channels
4.6.4. Using partners
Partner information can be used in many places of the application
View or search in your messages
In the grid of your messages, you can directly view the identified partners. You can also search or sort on these
fields.
Figure 4.130. Partners IN and OUT in list of messages
The information is also available in the screen with the detail of a message.
200
Channels
Figure 4.131. Partners IN and OUT in MessageDetail screen
Statistics
You will soon get access to the statistics by partner IN or partner OUT (now only by channel, gateway IN or
gateway OUT).
Related items
Related items allow you to navigate very quickly through the application
201
Channels
Figure 4.132. Related items of partner
In the processing of messages
Coming soon. The partners infos are accessible via metadata. You can access and use them.
It is very useful to use in routing, to select your channels based on the sender or the receiver.
4.6.5. Be compliant to GS1.
Babelway offers all the tools needed to be compliant with GS1.
If you need this, contact our support team to activate the option in your environment. You will have access to a
new partner tab GS1, with all the info required by GS1. You will also have access to the generation of all reports asked by GS1.
202
Channels
Figure 4.133. Partners - GS1 tab
4.6.6. Automatic Population of your Partners List
The import partners page allows you to import all your partners from a CSV file.
Figure 4.134. Importing Partners From CSV - General
203
Channels
CSV File
The CSV file contains the list of partners you wish to import and is formatted using UTF8 (without BOM).
The first line must contain the column headers for the values you wish to import. The file must only contain
existing columns and may not include system columns such as "Environment", "Creation date", "ID"... Below is a working CSV sample:
Note
"PartnerIdentifiers";"Name";"Description"
"OTHER:123456";"Julien Inc.";"Supplies"
"OTHER:654987";"Bertrand & Co";"Mergers and Acquisitions"
"OTHER:123478";"Mathieu Square";"Music Duet"
All the other lines in the file represent a new partner. Trying to modify existing partners will trigger an import error.
Values for most columns can be written out in plain text. The following types require a specific format for
babelway to interpret them properly:
• DateTime: Accepted formats are "dd/MM/yyyy HH:mm:ss" and "yyyyMMddHHmmss" or your preferred user format (see environment preferences).
• Date: Dates are expected in the following format: "DD/MM/YYYY" or "YYYY-MM-DD"
• Partner Identifiers: These should be presented as a comma separated list of identifiers ("CODE:Value").
For example: "VAT:BE1234567890" or "VAT:BE1234567890,GLN:1234567890123" are valid partner
identifiers.
Delimiter Character
The delimiter character separates different values in a given line.
Quote Character
Text between your "Quote Character"s will be handled as a single value/entry.
4.7. Lookup tables
Lookup tables are tables of values, that can be accessed by transformations to replace incoming values by corresponding outgoing values (For example, when your B2B partner is using different items codes than your own
items codes).
Lookup tables are not bound to a specific channel, but are defined at the level of your environment, and can be
accessed by all transformations. It is even possible to make them available to other environments.
4.7.1. Lookup tables list
The List of lookup tables screen shows you all the lookup tables defined in your environment. From here, you
can easily edit them, or create new ones.
This screen is accessible by clicking on the menu Channels, then the sub-menu Lookup tables
204
Channels
Figure 4.135. List of lookup tables
Name
A name that identifies the lookup table.
Description
A free description for the lookup table.
Columns
The names of the columns of the lookup table (separated by commas).
Shared access key
When the lookup table is shared, its sharing access key. See lookup table details for more information.
Id
A technical identifier of the lookup table, automatically set by Babelway platform.
Created on
The date and time when the lookup table was created.
Last updated on
The date and time of the last modification of the structure of the lookup table.
You can click on an entry to view the details of the associated lookup table, or edit it. See lookup table details.
The Create lookup table action button allows you to create a new lookup table.
4.7.2. Create a lookup table
This page explains how to create a new lookup table.
Just click on the Create lookup table action button at the bottom of the lookup tables list screen.
The creation screen will ask you to choose a name and description for the table, and a name for each column
that you want to use. Just leave empty the columns that you don't want to use.
205
Channels
Figure 4.136. Creation of lookup table
The lookup table structure can be updated later from the Structure tab in the lookup table detail screen.
The Duplicate an existing lookup table action button available at the upper section of the creation screen, can
be used to duplicate an existing lookup table from the current environment or from another environment you
have access to.
Figure 4.137. Duplicate a lookup table
4.7.3. Lookup table detail
206
Channels
This page shows you all the details about the lookup table. It can be accessed from the lookup tables list screen.
The page contains the following tabs.
General
This tab contains the signaletic information of the lookup table, and offers actions that act on the whole lookup
table.
Figure 4.138. Lookup table detail - tab General
Id
Created On
Last Updated On
Name
Description
A free description for the lookup table.
Shared
207
Channels
If checked, the lookup table can be accessed from other environments. The other environment will just
need the sharing access key to be able to access it.
Sharing access key
The key used by Babelway' system to identify the lookup table.
Replication mode
Lookup table entries are synchronized among all messaging engine servers. In a normal situation (when all
servers are available and able to communicate), all entries are guaranteed to be correct, regardless where
messages are processed. The 'Replication mode' parameter controls the synchronization during stress periods, like the network disconnection of one of the servers. The 'loose' mode is fault tolerant, this means that
the messages processing will not be interrupted. However there is a very little chance of inaccuracy. When
the re-connections occurs, the system performs consistency checks and creates an alert if an entry was modified independently by 2 messaging engine servers. The 'strict' mode guarantees the exactness of the entries.
This mode implies that message processing will fail if the entry update cannot be replicated immediately to
all messaging engine servers. Use this for exact counters, like invoice number. This Default is 'loose'.
The Save action button allows you save the changes that you have made in this tab (name, description and sharing option).
The Delete table action button allows you to delete the lookup table, but is only accessible if the lookup table is
not used in any transformation.
The Duplicate table action button allows you to duplicate the lookup table, with an option let you choose
wheather to duplicate only table structure or table structure and table content.
Figure 4.139. Lookup table detail - duplicate table
Structure
This tab allows you to edit the columns of the lookup table.
208
Channels
Figure 4.140. Lookup table detail - tab Structure
Content
This tab allows you to view and edit content of the lookup table.
Figure 4.141. Lookup table detail - tab Content
• To update the value of a cell, just click on it. The cell will become editable, and you will be able to change
the value.
209
Channels
• To add new rows, click on Add an entry. A new row will be added at the bottom of the table. You can then
complete the values by updating each cell.
• To delete rows, click on Delete at the right of the line. The row will be removed from the table.
Don't forget to Save after applying the needed changes.
The Import data from CSV action button allows you to import the lookup table data directly from CSV file
without the need to create a channel to do that. See Automatic Population of Lookup table from CSV
The Create data import channel action button allows you to create a channel to import data in the lookup table
from an outside data source in an automatic way.
The Export data action button allows you to export existing lookup table data in CSV format.
Related items
This tab allows you to see in which transformations the lookup table is used.
Note that this list does not contain transformations within other environments using the table as a 'shared lookup table' or transformations using the table inside custom XPath or Xslt functions.
Figure 4.142. Lookup table detail - tab Related items
4.7.4. Use your lookup tables.
The lookup tables are almost exclusively used in transformations, to translate incoming values to outgoing values contained in the table.
This is explained in details in the help section about drag-and-drop transformations.
4.7.5. Automatic Population of Lookup table from CSV
Automatic Population of Lookup table allows you to import the lookup table data directly from a CSV file
without the need to create a channel to do so.
After creation of a lookup table you can import data from a CSV file by clicking on Import data from CSV action button under the Content tab as illustrated below:
210
Channels
Figure 4.143. Import action button under Content tab
This will automatically direct you to the the following page.
Figure 4.144. Lookup Tables Data Import from CSV page
You can upload your CSV file and select the parameters that match your CSV structure and then click on Import action button to complete the import process.
4.7.6. Automatic Population of Lookup table using Channel
Automatic Population of Lookup table allow you to import the lookup table data from outside data source.
After creation of a lookup table you can create a data import channel by clicking on Create a channel to import
data in the table as illustrated below:
211
Channels
Figure 4.145. Create a lookup table data import Channel
This will automatically create a data import channel in your account with predefined gateways and message
definitions
You can upload your CSV file directly from the created web gateway like the following example or you can
modify the channel to meet your requirements.
Figure 4.146. Lookup Tables Data Import Channel
212
Channels
In this example we have two fields (counterName and value)
And this the uploaded CSV file
1,1001
2,1002
3,1003
4,1004
4.8. Routing
Routing is used to choose which channel must process a message, when different channels share the same gateway in.
Routing is done at first step that is different for the channels. So if 2 channels use the same gateway in but different messages in, routing will take place at message in step, and define rules to choose which message in
must be chosen. If both channels use the same gateway in and the same message in but different transformations, routing will take place at transformation step, and choose wich transformation should be used.
As the routing only chooses the next element of the processing (message in, transformation or gateway out),
and not directly channels, it can happen that a channel has routing at multiple steps. Let's illustrate this by the
following example:
Figure 4.147. Channels that need routing
• The 3 channels share the same gateway in. A routing will be required.
• As the 3 channels also share the same message in, no routing is required at this step.
• When coming to transformation step, there are 2 potential transformations to be executed : a first routing is
required to choose between these 2 transformations.
• If second transformation is chosen ("Countries xml to csv-1""), a second routing wil be required when coming to gateway out step, because there are again two candidates ("Smtp out" and "Smtp out-1").
This example will be used for all screenshots of this chapter.
4.8.1. Routings list
The List of routings shows all the routings existing in your environment, one by line.
This screen is accessible by clicking on the menu Channels, then the sub-menu Routing
213
Channels
Figure 4.148. List of routings
The first five columns illustrate, in order, the five main steps of the processing of the messages : Gateway in,
Message in, Transformation, Message out and Gateway out. 3 cases are possible :
• The background is white. This means that this step precedes the step of the routing illustrated on the line, and
therefore that all channels involved in the routing share the same element for this step. The name of this element is displayed in the cell.
• The background is dark gray. This means that this is the step for which the routing must make decisions. The
number of choices is displayed in the cell. Click on the line to get more details about the involved elements
and the edit the rules for the decision. See routing detail.
• The background is light gray. This means that this step follows the step of the routing, and is therefore of no
interest for the routing. The cell is left empty.
The Channel columns just show you the names of all the channels that are involved in this routing. At the end
of the processing, the routing decisions will have chosen one of these channels.
You can click on a line to view the details of the routing, and edit all the its rules.
You can't directly create new routings. The routings will be automatically created when needed.
4.8.2. Routings detail
The detail of the routing allows you to edit all the rules to choose the next element to process.
Figure 4.149. Routing detail
The first part of the screen just summarizes when this routing will be used, by clearly showing which preceding
steps are shared by all the channels involved in this routing.
The second part of the screen displays all the rules. There is one line by possible candidate that can be chosen
by the routing. The columns of the table are:
214
Channels
Priority
Tells in which order the rules will be evaluated. The system first evaluated rules that have the lower priority. The evaluation of the rules is stopped as soon as the condition of a rule is satisfied, and the system
chooses the next element noticed in this rule.
Metadata
Tells which metadata will be used for testing the condition. For example, in the figure, the metadata
com_babelway_messaging_context_mail_subject has been selected. This means that the rule will be satisfied if the subject of the email used to receive the message matches the following expression. If you want
that your condition applies on the whole message, select com_babelway_messaging_context_message.
Please refer to Metadata chapter for a list and description of all available metadata.
Condition (regular expression)
A regular expression that the selected metadata must match to satisfy the routing rule. Please refer to Regular Expression in External References chapter in appendices for description and reference about regular expressions.
then choose...
The element that will be chosen as next element for the processing if the rule matches.
Channels
The channels that area still reachable after having chosen the rule. If you still get multiple channels, it
means that another routing will happen at a further step to decide between them.
As example, the rules illustrated in the figure before can be read :
• If the subject of the email is "Tutorial1", then choose the transformation "Countries xml to csv" (used in
Channel "Tutorial 1") as next step.
• If the subject of the email is "Tutorial2", then choose the transformation "Countries xml to csv-1" (leading to
Channel "Tutorial 2a" or "Tutorial 2b") as next step.
4.8.3. Edition of routings from channels section
It is also possible to edit the routing rules directly from the channel detail screen.
The edition is done exactly like in the routing detail screen. There are only a few differences, that will be explained here.
Figure 4.150. Edit routing in channel detail
215
Channels
The main difference is that this screen is channel-centric, while the routing detail screen is routing-centric.
• All the routings in which the channel is involved will be detailed.
• The rules that applies to the current channel will be emphasized. They have a blue background.
4.9. Test cases
Testing enables easy channel operation test and validation before channel deployment. A minimum of testing is
mandatory in order to validate a channel.
After a channel configuration, its operation should be tested. This is done by creating and running test cases,
that is feeding the channel with test input files and checking corresponding output results after processing.
During a test case running, message in, transformation and message out processes are executed and tested in
real conditions. Only both in and out gateway cannot be validated that way as they require external operations
not managed by Babelway interface.
Figure 4.151. Testing tab list of existing test cases
At opening, testing tab displays a list of test cases defined for the selected channel. An existing test cases can be
edited by clicking on its name in first column. A new test case can be created by clicking on Create Test Case
command. Both these operations open the Edit Test Case screen described hereunder.
In the same table, clicking on Run command in middle column will manually run selected test case and display
test results in Message Record screen described hereunder.
The boxes that are checked in the third column select test cases will be deleted by clicking on Delete Selected
command.
Edit Test Case
When you create a new test case or edit an existing one, following screen will be displayed:
216
Channels
Figure 4.152. Edit test case screen
Following parameters can be set according to your setup:
Id
Name
Success
Select one of following conditions for testing success:
if there is no error and it has been processed by this channel
Test is successful if no error occurred during processing, do the routing rules if routing is checked and look
at the end if the Message Record is in state "DONE" and that the Message Record's channel is the one
where the test case is configured.
if there is no error, the output equals the ExpectedMessageOut and it has been processed by this channel
Test is successful if no error occurred during processing, do the routing rules if routing is checked, check
that the channel of the message record is the one of the test case and checks if the output file is the same as
the file in the File Property "ExpectedMessageOut".
if an error occurs
Test is successful if an error occured during processing. This test is used to validate processing behavior in
specific cases and check that an error is properly returned in these cases.
217
Channels
if there is no error and it has not been processed by this channel
Test is successful if the status of the Message Record is set to DONE but also checks if the channel of the
Message Record is not the channel of the test case (meaning that the message did not generate any error
and it has been routed away from the channel of the test case). This allows you to test that the routing happens as expected.
ExpectedMessageOut
Upload message that will be compared to processed message during test.
MessageIn
Upload message that will be used as input for test.
Message Record
As a result of running a test, following message record screen is displayed. Click on More details command to
see all information.
Figure 4.153. Message record
From here you have access to all message files such as in and out messages in defined format as well as pro218
Channels
cessed in and out XML messages.
The Status field indicates if message processing was successful or not. Next to it, between brackets, the test result is added as Test Successful or Test failed.
Note
All existing tests will be run at channel deployment time. If at least one of them fails, deployment will
be aborted.
4.9.1. Test case detail
Note
Describe all the fields and actions of all tabs.
Channel
The channel used by this test case, acccess it following the link.
Name
Description
4.10. Certificates
The keystore is the page where you can modify the keystore specific to your account.Each Babelway account
environment has its own keystore and is able to add or remove certificates without affecting other users.
A key is private information that is only known by your account environment and may not be shared with others.It holds the secret that only you can know to decrypt messages sent to you.
A certificate is public information that can be share with others and be known by anyone. It allows them to
verify that your signature could only have been generated with the key corresponding to the certificate.
Key/Certificate pairs can be self-signed but are usually generated by certificate authorities such as Thawte Consuting, Verisign Inc.,Comodo CA Limited….etc
You can Edit Keystore by clicking on "Keystore edit" on Certificates page
Each certificate entry in the table below can be downloaded in various formats, or revoked. These option are
available on the certificate's detail page, accessible by clicking on a table entry.
219
Channels
Figure 4.154. Manage Keystore Certificates
Certificates
This section lists all pair of key and certificates that are currently in you keystore. Those are typically used to
sign outgoing messages or decrypt incoming messages. In order to share the certificate with your partner, you
can download the certificate by clicking the certificate to access the details page, and using the Download link.
Note that the downloaded file will never include your private key and only contain your public certificate.
You can add new pair of key/certificate using a PKCS12 file under the Add new Certificate section.
Trusted certificates
This is the list of trusted certificates currently in your keystore. A trusted certificate corresponds to the public
certificate of one of your partners.
You can add a new trusted certificate either by using an https URL. In this case, the certificate linked to the
HTTPS page will be trusted. You can also add a new trusted certificate using the certificate file provided by
your partner.
In each case, you can select to trust the root of the given certificate. If you choose to do so, all certificates gen-
220
Channels
erated by the certificate authority will be trusted.
To read more about Https gateway See HttpClientOut Gateway
4.10.1. Certificate's Details
The certificate's details page regroups and displays all the useful informations about a certificate, and give access to several actions such as revoking the certificate, or downloading it.
Alias
An alias to easily identify the certificate.
Distinguished Name
A set of informations about the certificate, used to uniquely identify it.
Serial Number
Internal parameter used to classify certificates
Expiration Date
Date after which the certificate will no longer be valid.
Several actions are available, to help you easily manage every certificate in your keystore, and share them with
your partner or accross applications.
Download
Download the certificate in PKCS12 format.
Download PKCS7
Download the certificate in PKCS7 format.
Download SSH
Download the certificate's public key in pub format encoded as an ssh-rsa key.
Revoke
Definitely remove a certificate from your Babelway keystore
Related items
Using channels
Using gateways
All the Gateways that use this element.
Connected Message Definition (through extra-processing)
List of message definition that have an extra-processing related to this certificate.
4.10.2. Trust new certificate
221
Channels
Note
Alias
An alias that you can set to easily identify your certificate.
Certificate
Upload or give the location of the certificate when you trust.
Trust root certificate
Indicate if you want to trust certificates issued by the provider of the selected certificate.
4.10.3. Add a certificate
Note
Alias
An alias that you can set to easily identify your certificate.
Pkcs12 file
Upload your Pkcs12 file.
Pkcs12 password
The password required to use your Pkcs12 file.
4.11. Extra processings
An extra processing is an additional operation that must be applied on all messages.
Some examples are : extract a message from a zip file, sign a message, reject a message if it is a duplicate, ...
The extra processings can take place before of after every of the 5 main operations that are followed by messages within Babelway plaform (gateway in, message in, transformation, message out and gateway out).
The extra processings of an element can be accessed via the tab "Extra processings" of the screen that details
the element.
222
Channels
Figure 4.155. Extra processings
To add an extra processing, just click on Add extra processing. It will open a popup like shown in the following
screenshot, where you can just click on the wanted extra processing to add it. Don't forget to save.
Figure 4.156. Extra processings
If you use multiple extra processings on the same element, they will be executed in a predefined order, that you
can not choose. The extra processings are always displayed in the order of execution (first displayed extra pro223
Channels
cessing if also the first one to be executed). For example, in the screenshot above, zip unwrapping will be executed before relacement based on regular expression.
4.11.1. Extra processings on gateway IN
Zip unwrapping
This extra-processing allows to extract multiple files from a zip, and to process each of those files separately.
The parameters are :
File name pattern
Pattern (regular expression) for the file name in the zip of the files that will be extracted.
Automatically close errors
This extra-processing allows to define criteria to automatically close an error that occurs during the Gateway IN
step.
Error message patterns
The patterns that will be tested against the error message.
If the error message matches at least one of the patterns, the status of the message will automatically be set
to Error(closed).
Message identifier
This extra processing analyses the incoming message, and associates the following metadata to it:
universal_router_type
The type of document, like 'ORDERS', 'INVOIC', 'DESADV', ...
universal_router_format
The format of the message, like 'EDIFACT', 'X12', 'IDOC', ...
universal_router_version
The version of the message format. For example, for EDIFACT, version can be '96A', '01A', ...
universal_router_sender
The identification of the sender of the message
universal_router_receiver
The identification of the receiver of the message
universal_router_key
The intergration of the five previous fields, separated by '_'. The goal of this field is to simplify the writing
or routing rules, or of keys of messages, that want to use all of the above fields.
The metadata will typically be used by a following routing. As an example, suppose that you receive orders in
different formats with the same gateway. This extra processing can be used to identify the following formats:
224
Channels
EDIFACT, X12, IDOC (xml or flat file), RND, VDA, cXML. This information can then be used to route the
message to the correct message definition.
This extra processing doesn't take any parameter.
4.11.2. Extra processings on message definition IN
Save input file
Allows you to save your input file as a metadata, for future use as explained in the next steps.
Metadata
The metadata in which you want to be saved in the input file.
Duplicate incoming message
Allows to duplicate the incoming message, and inject it into another channel.
Step
When the incoming message must be duplicated in the process of the original message. If Duplicating the
message later the message will not be duplicated if the message fails some validation.
Target gateways
The gateways to which the duplicated message will be sent.
gateways.
Zip unwrapping
Allows you to extract your input file from a zip. It also allows you to save other files of the zip to be reused, in
the next steps.
As an example, suppose that your channel is designed to process xml orders. But instead of directly receiving
the xml order from your partner, you receive a zip file, that contains the expected file order.xml, and also a file
order.pdf. You can just extract your order.xml file by using this extra processing with the pattern 'order.xml'. If
you need it for later use, you can also save the pdf file for future use (reuse in your transformation, reinclude it
in archive in message out, ...)
File name pattern
Pattern (regular expression) for the file name in the zip of the file that will become your input message.
First match is used.
Other files to save
Allows you to save other files of the zip for future use. For every file that you want to save, you have to
225
Channels
specify the pattern of the file name in the zip , and the name of the metadata in which you want to save the
content. If one pattern matches multiple files, it is possible to save them all if you guarantee to generate a
different metadata name for each. This can be achieved by using the capturing groups of the regex in the
metadata names. Ex: if your pattern is (.*\.csv) and your metadata name is attachment-$1, processing with
files file1.csv and file2.csv will result in two metadata as follows attachment-file1.csv and attachmentfile2.csv .
Pdf unwrapping
Allows you to extract your input file from a pdf. It also allows you to save other files of the pdf to be reused in
the next steps.
As an example, suppose that your channel is designed to process xml orders. But instead of directly receiving
the xml order from your partner, you receive a pdf file, with your xml order included as a pdf attachment. You
can extract your order.xml file by using this extra processing with the pattern 'order.xml'.
File name pattern
Pattern (regular expression) for the file name in the pdf of the file that will become your input message.
First match is used.
Password
Password, if any, to open the pdf file.
Other files to save
Allows you to save other files of the pdf for future use. For every file that you want to save, you have to
specify the pattern of the name of the pdf attachment(first match), and the name of the metadata in which
you want to save the content.
S/MIME unwrapping
Allows you to extract your input file from a S/MIME envelop. It also allows you to save other files of the pdf to
be reused, in the next steps.
File name pattern
Pattern (regular expression) for the file name in the S/MIME of the file that will become your input message. First match is used.
Other files to save
Allows you to save other attachments of the S/MIME envelop for future use. For every file that you want to
save, you have to specify the pattern of the name of the pdf attachment (first match), and the name of the
metadata in which you want to save the content.
Signature key alias
The alias of the key (in the keystore of your environment) that will be used to check the signature.
Verify signature
Enables or disables the check of the signature.
PGP unwrapping
226
Channels
Allows to decrypt a file encrypted using PGP.
PGP Private Key
Private key to be used to decrypt the message.
Password
Password to access the private key.
Validation of Xml Signature.
Allows you to validate the Xml Signature.
Replacement based on regular-expressions.
Allows you to make a global search and apply regular-expression replacements on your input file, before it is
analyzed.
You can define more than one pair of regular-expressions to find & replace pattern.
Replacements
List of regular expressions and replacement patterns that will be applied on your document for every match.
Remove ASCII Control characters (except line feed)
Allows you to remove ASCII Control characters from input file.
Characters removed are : [x00-x09]|[x0B-x0C]|[x0E-x0F]|[x10-x1F]|x7F
Message identifier
This extra processing analyses the incoming message, and associates the following metadatas to it:
universal_router_type
The type of document, like 'ORDERS', 'INVOIC', 'DESADV', ...
universal_router_format
The format of the message, like 'EDIFACT', 'X12', 'IDOC', ...
universal_router_version
The version of the message format. For example, for EDIFACT, version can be '96A', '01A', ...
universal_router_sender
The identification of the sender of the message
227
Channels
universal_router_receiver
The identification of the receiver of the message
universal_router_key
The sequence of the five previous fields, separated by '_'. The goal of this field is to simplify the writing or
routing rules, or of keys of messages, that want to use all of the above fields.
The metadata will typically be used by a following routing. As an example, suppose you receive orders in different formats with the same gateway. This extra processing can be used to identify the following formats: EDIFACT, X12, IDOC (xml or flat file), RND, VDA, cXML. This information can then be used to route the message to the correct message definition.
This extra processing doesn't take any parameter.
Trustweaver processing
Calls upon Trustweaver to process your message. See http://www.trustweaver.com for more informations.
Trustweaver environment
The Trustweaver environment that is targeted by the process.
Trustweaver country
The country for which the Trustweaver process will be done.
Validation Outcome code pattern
A pattern designating the validation outcomes that are accepted.
Trustweaver client key alias
The alias of the key (in the keystore of your environment) that will be used to authenticate to Trustweaver.
Contact email address
The email address that will be provided to TrustWeaver as the point of contact for all registered branches.
Xslt transformer
Applies a xslt to correct your message. It is applied on the internal xml representation of the message (after the
message have been analysed and converted).
Be aware that the message resulting from your transformation must conform with the message definition (tree
structure).
Xslt
The transformation that must be applied.
This extra-processing allows to define criteria to automatically close an error that occurs during the message
definition IN step.
228
Channels
to Error(closed).
4.11.3. Extra processings on Transformation
Automatically retry transformation on error
Automatically retry transformation on error
This extra-processing allows to define criteria to automatically retry a transformation if an error occured.
Retry strategy
Allows you to determine the time interval that needs to be used for the retries.
Email Recipients
Address to which an email will be sent if the a retry is scheduled. You can add a comma separated list of
recipients or a metadata.
Email Subject
Email message subject. You can use metadata.
Email body type
[text/plain , text/html] default is text/plain.
Email body
Email message Body. You can use metadata.
This extra-processing allows to define criteria to automatically close an error that occurs during the Transformation step.
to Error(closed).
4.11.4. Extra processings on message definition OUT
Xslt transformer
229
Channels
Applies a xslt to correct your message. It is applied on the internal xml representation of the message (before
the message is converted to the output format).
Be aware that the output of your transformation must be compatible with the internal representation of Babelway for this message format.
Xslt
The transformation that must be applied.
Line delimiter converter
Converts all line delimiters to the line delimiter that you choose. The original file can have its line delimiters in
any style (Unix, Windows, Mac).
The parameters are:
Line delimiter
The line delimiter that you want to be used in your output file.
Xml Signer
Signs an Xml.
The parameters are:
Key alias
Alias of the key (in your keystore) that will be used to sign the Xml.
Digest method
The digest method that will be used during the signature of the Xml.
Signature Method
The signature method that will to be used to sign the Xml.
Signature transformation
The transformation that will be used to sign the Xml.
You have the choice between an inclusive Canonicalization or an enveloped signature.
Xpath to the target node's URI
The Xpath that will allow the extraction of the URI of the root node of the subtree that needs to be signed.
If not defined, the whole xml document will be signed.
xmlSigner
Pdf wrapping
Allows you to create a pdf that will contain your output file in attachment.
The parameters are:
230
Channels
Pdf from template
The template that will be used to create and container the pdf. You have here 4 possibilities :
• You directly provide a pdf file. This pdf file will be used as it is, and the extra processing will just add
the requested pdf attachments.
• You provide an xhtml template for the pdf. This template will be converted into a pdf. This option can be
useful if you want to use some metadata in your pdf template (current date, ...).
• In the parameter 'Pdf from metadata', You provide the name of a metadata containing the pdf you want to
use. This metadata must be have already been populated earlier in the process of the message.
• You don't provide any file. A default (empty) pdf template will be used. This option can for example be
useful if the pdfWrapper is just used to benefit from the pdf digitial signature functionnality.
Pdf from metadata
The name of the metadata containing the pdf. This metadata must be have been already populated earlier in
the process of the message, for instance by extracting it from a zip file.
File name
The name that your output file will have in the pdf.
File description
The description that your output file will have in the pdf.
Attachments
Other files that must be added to the pdf. For each individual file, you will have to stae the name that the
file will have in the pdf, and the name of the metadata that contains the content.
Pdf resizer
Allows you to resize an output pdf.
The parameters are:
Page size
The page size requested for the new pdf (A4, A5, LETTER, ...). The default is A4.
Offset X
Specifies the zone in the input pdf that will be copied to the output pdf. The default is 0.
Offset Y
Specifies the zone in the input pdf that will be copied to the output pdf. The default is 0.
Position X
Specifies the where to zone copied from the input pdf will be placed on the page in the output pdf.
Position Y
Specifies the where to zone copied from the input pdf will be placed on the page in the output pdf.
Scale X
Specifies the zoom ratio that must be applied when copying requested zones from the input to the output
pdf. The default is 1.
231
Channels
Scale Y
Specifies the zoom ratio that must be applied when copying requested zones from the input to the output
pdf. The default is 1.
Pdf Letterhead
Allows you to set a letterhead to your output pdf file.
The parameters are:
Letterhead pdf
The pdf file that contains the letterhead.
Page order
When the letterhead pdf contains multiple pages, it tells you which page of the letterhead must be used for
every page of the output pdf file. The possible values are described hereafter. For every value, we also
show as an example the result of the association for a output pdf file that would contain 5 pages (1, 2, 3, 4
and 5) and a letterhead pdf that would contain 2 pages (A, B).
• Match forward. Repeat last page. starting from the first page, all pages of the two pdfs are used together.
If output pdf has more pages that the letterhead model, the last page of the letterhead is used for all the
subsequent pages. In our example, it would give the following result : 1:A, 2:B, 3:B, 4:B, 5:B.
• Match backward. Repeat first page. starting from the last page, all pages of the two pdfs are used together. If output pdf has more pages that the letterhead model, the first page of the letterhead is used for all
the previous pages. In our example, it would give the following result : 1:A, 2:A, 3:A, 4:A, 5:B.
• Repeat all pages. all pages of the letterhead are repeated till the end of the output pdf. In our example, the
following result would be: 1:A, 2:B, 3:A, 4:B, 5:A.
Pdf Appendix
Allows you to add extra pages to your output pdf file.
The parameters are:
Pdf to add
The pdf file that wil be appended at the end of the existing pdf.
Add attachments to a pdf
Allows you to add attachments to your output pdf file.
The parameters are:
Files to add
The attachments that must be added to the pdf. For every attachment, you have to state the name that the
file will have in the pdf, and the name of the metadata that contains the content.
PdfA converter
Transforms a pdf to make it PDFA1B compliant.
232
Channels
Pdf signer
Allows you to sign your output pdf file.
The parameters are:
Key alias
Alias of the key (in your keystore) that will be used to sign the pdf .
Reason
Text that will be associated to the signature.
Show signature ?
Allows you to add an image to your pdf to show the signature.
Signature lower left X
Position (lower left X) where the signature image will be displayed. Only if you choose to show signature.
Signature lower left Y
Position (lower left Y) where the signature image will be displayed. Only if you choose to show signature.
Signature upper right X
Position (upper right X) where the signature image will be displayed. Only if you choose to show signature.
Signature upper right Y
Position (upper right Y) where the signature image will be displayed. Only if you choose to show signature.
Signature image
Image used to show the signature. Only if you choose to show signature.
Timestamp method
Allows you to timestamp your output pdf.
Timestamp authority url
If you choose the external as timestamp method, the url to be called for the timestamping.
Timestamp authority login
If you choose the external as timestamp method, the optional login to use for the call.
Timestamp authority password
If you choose the external as timestamp method, the optional password to use for the call.
Zip wrapping
Allows you to wrap your output file from a zip. It also allows you to add other files in the zip.
The parameters are:
File name
The name that your output file will have in the zip.
Other files
Other files that must be added to the zip. Metadata = Pattern to match the metadata containing the file to attach. Filename = name of the file in the zip. If one pattern matches multiple files, it is possible to put them
233
Channels
all, if you guarantee to generate a different filename name for each one. This can be achieved by using the
capturing groups of the regex in the filename. Ex: if your metadata pattern is attachment-(.*) and your filename is \1, processing with two metadata attachment-file1.csv and attachment-file2.csv will result in files,
file1.csv and file2.csv.
PGP wrapping
Allows you to encrypt a file using PGP.
The parameters are:
PGP public Key
Public key to be used to encrypt the message.
Output in ascii
If checked, the PGP output follows the Ascii armored format, if not the output is in binary.
S/MIME wrapping
Allows you to wrap your output message in a S/MIME envelop.
The parameters are:
File name
The name that your output file will have in the S/MIME envelop.
Content type
The content type that will be associated to your output file in the S/MIME envelop.
Signature key alias
The alias of the key (in the keystore of your environment) that will be used to generate the signature.
Partner key alias
The alias (in the keystore of your environment) of the certificate of your partner. It will be used to crypt the
S/MIME message. If left empty, the message will not be crypted.
Replacement based on regular-expressions.
Allows you to make a global search and apply regular-expression replacements on your output file.
You can define more than one pair of regular-expressions, find & replace pattern.
The parameters are:
Replacements
List of regular expressions and replacement patterns that will be applied on your document for every match.
Create messages from metadata
Allows you to create new messages, with content from current metadata.
The parameters are:
234
Channels
Target gateways
The gateways to which the new message will be sent.
Metadata and names
Metadata containing content for messages to create. Metadata = Pattern to match the metadata that contains
the contents for new messages. Filename = fileName of the new messages. If one pattern matches multiple
metadata, a new message will be generated for each metadata. You can use the capturing groups of the
regex in the filename. Ex: if your metadata pattern is attachment-(.*) and your filename is \1, processing
with two metadata attachment-file1.csv and attachment-file2.csv will result 2 new messages files file1.csv
and file2.csv.
gateways.
Message Validation
Allow you to validate a message against a metadata.
The parameters are:
Fail on error
Create an error if the message is not valid.
Set status on error
If 'Fail on error' is not selected, this puts the message in error without creating a ticket.
Metadata name
Name of the metadata containing the expected result.
Regex to ignore
List of regular expression to ignore.
Date to ignore
List of date format expression to ignore. Dates are expressed using the regular java format like : yyyyMMddhhmmss.
Message Unwrapper (Deprecated)
Allows you to extract message from zip or pdf
The parameters are:
Unzip
Extract the message from a zip container.
Pdf attachment
Extract the message from an attachment in a pdf container.
Parse pdf
Create an XML from extracted pdf
Message
235
Channels
Regular expression to extract the message
Extra metadata
Regular expression to extract an extra file and store it in a metadata.
Extra metadata encoding
encoding of the extra metadata
Extra metadata name
Metadata name to use. Default is the same as the real name.
Save Original as
Same, the original message in a metadata with this name.
Save extracted as
Same, the unzip / unpdf message in a metadata with this name.
Other attachments
Regular expression to save other attachments
This extra-processing allows to define criteria to automatically close an error that occurs during the message
definition OUT step.
to Error(closed).
4.11.5. Extra processings on gateway OUT
This extra-processing allows to define criteria to automatically close an error that occurs during the Gateway
OUT step.
to Error(closed).
4.12. Metadata
Metadata are data that are associated with the processing of the message, besides of the processed input and
output files.
236
Channels
For example, some metadata are the date and time when the message was received, the channel that processes
the message, informations about the sender of the message, ... The complete list of system metadata can be
found here.
Metadata is useful to customize your output messages or notifications. See below some usage examples.
It is also possible that you define your own metadata. See drag-and-drop transformation details
4.12.1. Metadata usage
This page shows you some examples of locations in the application where metadata can be used.
Changing value assigned to a system metadata in drag and drop transformation
See details in drag-and-drop transformation.
Using metadata to customize messages and file names
You can use system or user defined metadata in your output gateways and email notification configuration. The
metadata values can be used to name output files sent through output gateways or as part of a notification email
subject and or body. The metadata used may even be different for success or failure messages as shown in the
figures below.
System metatada are referenced using syntax {com_babelway_messaging_context_***}. A list of available
system metadata with returned variables and examples is available in System Metadata appendix.
Figure 4.157. System metadata used to customize notification emails
237
Channels
Figure 4.158. System metadata used to customize file names
User defined metatada are referenced using syntax {user-defined-property:your_metadata} where
your_metadata is the name of your user defined metadata you want to reference it as illustrated in the following
example where the earlier user defined metadata is used as a name for the file sent as email attachment.
238
Channels
Figure 4.159. User defined metadata used to customize attachment name
Concatenate values from a loop in a metadata
If you want to concatenate multiples values from a loop in a single metadata such as a message reference or a
user defined metadata, you have 2 options:
1. Use a full custom xpath:
• Do not map any loop.
• Create a Xpath custom expression such as:
string-join (YOUR_XPATH, 'YOUR_SEPARATOR')
Where YOUR_XPATH is the path to all the elements you want to concat such as:
/ediroot/interchange/group/transaction/loop/segment[@Id='NAD' and element[@Id='NAD01'] =
'BY']/element[@Id='NAD02']/subelement[@Sequence='1']
or
/csv/line/field1
Or drag a repeated element (such as the line hereover) on the custom function. All field1 elements under the re239
Channels
peated element will be concatenated and separated by the given separator.
$arg1/field1
YOUR_SEPARATOR is the separator between two elements of the list such as ' - ' for example.
2. Use the functions get-metadata and set-metadata
• Map the loops to the output metadata
• Create a Xpath custom expression with the following expression:
metadata-util:put($MSG,'com_babelway_messaging_context_message_reference', bfn:concat
('YOUR_PREFIX', 'YOUR_SEPARATOR', 'YOUR_SUFFIX', metadata-util:get($MSG,
'com_babelway_messaging_context_message_reference'), $arg1))
Where
• YOUR_PREFIX is the prefix added at the beginning of the result, ex: ' here is the list of value: '
• YOUR_SEPARATOR is the separator added between the different elements, ex: ' – '
• YOUR_SUFFIX is the suffix added at the end of the result ex: [i ' '[/i]
• Drop the value of the element to the expression (= $arg1 )
• Map the expression to the metadata
4.12.2. System Metadata
System metadata is metadata that is defined in the system and contains useful information relating to the message being processed. See Metadata chapter for reference and examples of use.
Table 4.1. List of System Metadata
Code
Name
{com_babelway_
saging_context
_message}
mes- Message context
{com_babelway_
saging_context
_accountId}
mes- Account ID
Description
Example
The ID of the account 25010
which has the processing
Hub.
{com_babelway_ mes- Hub ID
saging_context _hubId}
The ID of the account en- 25030
vironment which processed the message
{com_babelway_
saging_context
_channelId}
mes- Channel ID
The ID of the channel 26885
which is used in processing the message.
{com_babelway_
saging_context
mes- Receive Day
The day in which the 20090503
message was delivered by
240
Channels
Code
Name
_receiveDay}
{com_babelway_
saging_context
_receiveTime}
Description
Example
the system.
mes- Receive Time
The time in which the 20090503-163446
message was delivered by
the system.
{com_babelway_ mes- Receive Time extended
saging_context
_receiveTime_extended}
The extended
time.
receive 20090503-163446-968
{com_babelway_ mes- Message reference
saging_context
_message_reference}
A reference for the mes- ABNAmrosage
Funds_AAA.xls
{com_babelway_
saging_context
_client_reference}
mes- Client reference
A reference for the client
{com_babelway_
saging_context
_in_filename}
mes- Input file name
The name of the input file ABNAmroFunds_AAA.xls
{com_babelway_
saging_context
_in_filename
_no_extension}
mes- Input file name
The name of the input file ABNAmroFunds_AAA
with no extension.
{com_babelway_
saging_context
_out_filename}
mes- Output file name
The name of the output 20090430_ABNAMROL
file
UX _MMF.xls
{com_babelway_
saging_context
_out_fileContent}
mes- Output file content
{com_babelway_
saging_context
_mail_from}
mes- The sender email address
The email address from [email protected]
which the message was
sent.
{com_babelway_ mes- The receiver email ad- The email address to [email protected]
saging_context _mail_to} dress
sent.
{com_babelway_
saging_context
_mail_subject}
mes- Email message subject
The subject the email FW:
Abnamromessage received by the funds_AAA.xls - MMF system.
20090430
{com_babelway_
saging_context
_mail_body}
mes- Mail body
{com_babelway_
saging_context
_mail_send_date}
mes- Mail sending date
{com_babelway_
saging_context
mes- AS2 message receive date The receive date of the 1241504709696
AS2 message.
javax.mail.internet.
MimeMultipart@13dc44a
The sending date of the 1241422103000
email message.
241
Channels
Code
Name
Description
Example
_as2_receive_date}
{com_babelway_
saging_context
_as2_send_date}
mes- AS2 send date
The sending date of the
AS2 message.
{com_babelway_
saging_context
_as2_from}
mes- AS2 from address
The AS2 sender address.
C4NETBE
{com_babelway_ mes- AS2 to address
saging_context _as2_to}
The AS2 receiver ad- BABELdress.
WAY_AS2_25010
{com_babelway_
saging_context
_as2_message_id}
The ID of the AS2 mes- d19bc8_1210d8ea134_-4
sage.
5ec @C4NETBE_host
mes- AS2 message ID
{com_babelway_ mes- Input user
saging_context _in_user}
The
username
from -ftp login: 'fc-invoice'
sent (such as the ftp login
name or sender email address)
4.13. Change Log
Each time you push on the "save" button in a component, a revision is created, that keeps track of all the
changes done. This allows to know the state of your components at any given point in time. The Revert function uses those revisions in order to go back in time and put your components at a given revision.
The change log can be viewed for the whole environment, or by element.
4.13.1. Environment change Log
Each time you click on the "save" button in a component, a revision is created. This allows you to know the
state of your components at any given point in time. The Revert function uses those revisions in order to go
back in time and put your components at a given revision.
List of revisions
To view the list of revisions click on Change Log in the menu below Channels
The list of revisions is displayed as illustrated below:
242
Channels
Figure 4.160. list of revisions
The revisions are listed from the latest to the oldest. So your last modification is displayed at the top of the list.
By definition, the last revision corresponds to the last time you clicked on "save'. So by definition, there would
be no difference between the current version of your components and the last time you clicked on save.
All the revisions below the first are old states of your components. There is a timestamp (which represents
when you clicked on 'save'), the user who clicked on 'save' and a small description limited to the components
(i.e. channel, message in, message out, transformation, test, ...) that have been modified.
4.13.2. Elements change Log
Note
Explains here that is it possible to view the element change log in a tab of gateway|MD|transformation
detail screen. Explains the info, how to revert, ... This page will be linked from these screens.
4.14. Reuse and save time
The reuse and save time zone allows you, when you need to configure some element, to make all the configuration in just one click, by reusing elements that have been previously defined.
In this zone, the system will always try to make the suggestions that are the most relevant to your usage, depending on the whole known context (what you have already selected, other elements of the channel, ...). These
suggestions can be of different types :
• Element from the Babelway catalogue. The Babelway catalogue contains many message definitions or gateways used by main retailers. These elements are ready to use, and can just be copied to your environment.
• Elements that you already defined in your environment. You will be able to use them, or duplicate them in
just one click.
243
Channels
• Elements that are in other environments to chich you have access.
• Examples, that are useful to make your first steps and test the application.
• Suggestions. In some cases, we can deduce what you need from what you already did. For example, MessageDefinitions can in some situations be deduced from the gateway you selected.
Figure 4.161. Reuse with different types of suggestions.
This zone is available when you want to create an element ( gateway creation, MessageDefinition creation,
transformation creation, channel creation or partner creation) and in the ChannelDetail screen.
4.14.1. Search and Reuse
To filter the elements, you just need to type your criteria in the search bar, at the top of the zone. In the following example, only entries that match "Colruyt" will be returned.
Figure 4.162. Reuse search.
If you use multiple words, like 'Colruyt Order', all the word will be searched separately. Only entries that contains all of the words will be returned.
244
Channels
If you specify a given type in the creation form, search will also be limited to elements of this type. IN the following example, only invoices of type EDIFACT will be returned.
Figure 4.163. Reuse search.
By default, only first 5 entries by category will be returned. If you want to view more, you can use the More action to view the full list, and have access to more advanced search.
Figure 4.164. Reuse search - more
245
Channels
Figure 4.165. Reuse search - more results
When you have found the element that you want to use, just click on it.
Figure 4.166. Reuse search - more results
4.14.2. Using the Babelway catalogue
The catalogue is a large repository of elements predefined by Babelway. These elements are ready to use, and
you can just copy them into your environment and use them.
The catalogue contains many message definitions or gateways used by main retailers, ... Before thinking to
define the message definitions or gateways for your partner, always check that it is not already defined in our
catalogue !
246
Channels
Figure 4.167. Catalogue items.
4.14.3. Using or duplicating elements that you already defined.
In the section of the results names You already defined, you will find elements that you have already defined in
your current environment, and be able to use them again.
Figure 4.168. Reuse - already defined elements.
If you are creating a new item ( in gateway creation screen, in MessageDefinition creation screen, in transformation creation, screen, in channel creation screen, ...), reusing an existing element means duplicating it.
Figure 4.169. Reuse - element duplicated.
If you are in the ChannelDetail screen, and it is the first time you use this element, the element will just be assigned to the channel.
Figure 4.170. Reuse - element set in channel.
If you are in the ChannelDetail screen, and the selected element is already used in other channels, you will get
the option of duplicating or sharing it.
247
Channels
Figure 4.171. Reuse - element set in channel.
4.14.4. Accessing elements from other environments.
You can also access and reuse elements from other environments you are allowed to access.
These elements are not returned by default by the pertinence algorithm. To use them, you will always have to
use the advanced search (click on More ).
Figure 4.172. Use element from another env - Click on More
248
Channels
Figure 4.173. Use element from another env - Choose environment
4.14.5. Using examples or suggestions.
When you are making your first steps with the application, you will have access to some examples. These examples are ideal to be able to setup a first channel in a few seconds, and being able to test the application.
The application can also make you suggestions, based on the other elements present in your channel.
In the following example, a gateway IN of type MessageRecord has already been set to the current channel.
The application will automatically suggest you just one MessageDefinition to use, because it knows the format
of files generated by this gateway.
249
5
Admin
This section explains what can be found under the admin section menu.
5.1. Personal data
Manage and edit your personal information such as username, name, email address, password...
Figure 5.1. My Profile
The following information is displayed:
Username
The username you entered at registration time (cannot be modified).
Email
Your email address (mandatory). If you change it, an email will be sent to this email address to verify it.
First name
Your first name (optional, can be modified).
Last name
Your last name (optional, can be modified).
250
Admin
Phone
Your telephone number (optional, can be modified).
After your registration, an email is sent to your email address in order to verify it. You have 7 days to click on
the verify link. After that, your user will be blocke. A reminder is displayed when you log in and in this page
Figure 5.2. Email address verification reminder
Commands
Save
Save your modifications.
Edit password
Enables you to change your password.
Verify email address
An email will be sent to your email address in order to verify it
Select, enter or change parameter values then click on Save to save your changes or on Back return to previous
screen without saving changes.
Click on Change Password command to open following screen and change your account password.
Enter old and new passwords, confirm new password then click on Change Password to save your new password or on Back return to previous screen without saving change.
Figure 5.3. Edit screen
5.2. Environment settings
251
Admin
An account environment contains a collection of one or more channels that are managed together.
In this section, you can change settings that affect your whole environment. You can also create additional environments if required.
5.2.1. General
The General tab allows you to view or change how your account and environment is identified.
If you have multiple environments, it is important to name them correctly, to ease the comprehension of the
content of each of them.
Figure 5.4. Environment settings - General
Account name
The name of your account. By default, this name includes your login name.
Account Password Policy
The password policy defines the security level used for the authentication of all the users having access to
this account.
The following policies exist:
• Regular: The user password must have a length not less than 6 characters.
• Strong: The user password must contain a mix of UPPER-CASE and lower-case characters as well as
numbers, and have a length not less than 8 characters. A mandatatory password renewal is enforced at
least every 90 days. Each new password should differ from the previously used ones.
Only the Babelway administrators can modify this setting.
Environment name
The name of the current environment. By default, this name is "Environment X" (X is the count of environments in your account).
252
Admin
Id
A unique identifier for your environment, automatically set by Babelway platform.
5.2.2. Messages
This tab allows you to view and change the parameters of your environment that affect how the messages are
processed.
Figure 5.5. Environment settings - Messages
Message Storage Duration
How long the messages processed in this environment will be kept. The possible values are 15 days, 1
month, 3 months, 1 year or 10 years for legal documents that must be kept longer. The value set here is a
default value at environment level, and will only be used if a more specific value is not set at channel level.
Messaging Engine
This parameter defines on which "Messaging Engine" an environment is running. A Messaging Engine
groups the different components processing and storing messages. This leverages Babelway multi cloud architecture allowing to load balance operations on several infrastructures.
IP addresses
This parameter defines the IPs of components of the "Messaging Engine" on which an environment is running.
Use Secure Chain
Defines if the environment is using Babelway Secure Chain mechanism. The secure chain is a key part of
Babelway legal archiving solution.
Special Data Privacy
If true, only users with an explicit right on the environment have access to the content of the messages and
user management. This prevents Babelway support to see the content of messages.
253
Admin
SLA Capacity
1 or more, is a measure of the processing capacity associated to the account environment. It defines the
maximum number of messages (in 10kB chunk) that can be processed per minute.(Service Level Agreement)
5.2.3. Partners
This tab allows you to add specific fields to the Partner model. See Partners section for a full explanation about
partners.
The fields that you add here will be available in add or edit a Partner, or in the list of Partners.
Thanks to this,in the Partners sections you can also have all the fields that are specific to your business, or important for you but non-standard.
Figure 5.6. Environment settings - Partners
For every field, you can choose its name and its type.
The type is important, as it helps the application validate the data that you encode, and eases the manipulation
of the data. For example :
• If you tell the application the possible values that a String may contain (when the field can only have a
known set of acceptable values), the interface will offer you a dropdown menu for selecting the values, this
guarantees that you can not enter another value in error.
254
Admin
• If you choose an Integer type, you will be guaranteed to have only numbers in the field, and the interface will
sort the values numerically (ex: 1, 2, 10) instead of alphabetically (1, 10, 2).
5.2.4. Document types
Documents allows you to have a business view on the processed messages.
In this tab, you can configure which documents you want to use, and configure the fields that you want to have,
or how to interface must display them.
Figure 5.7. Environment settings - DocumentTypes
The following parameters are available :
Name
The name of the document. Please note that this name will be used as an identifier to identify the Docu255
Admin
mentType, and is therefore independent of the language, but you will be able to define labels for this DocumentType in every language (see parameter Labels).
Keep duration
How long the documents must be kept.
Fields
All the fields that you want to have for this DocumentType.
For every field, you can choose its name and its type.
The type is important, as it helps the application validate the data that you encode, and eases the manipulation of the data. For example :
• If you tell the application the possible values that a String may contain (when the field can only have a
known set of acceptable values), the interface will offer you a dropdown menu for selecting the values,
this guarantees that you can not enter another value in error.
• If you choose an Integer type, you will be guaranteed to have only numbers in the field, and the interface
will sort the values numerically (ex: 1, 2, 10) instead of alphabetically (1, 10, 2).
A special field UniqueKey can be used as a user identifier for the Document. It can be used in extractors to
indicate that multiple extractions concern the same logical document, and result in updates instead of creation of a new document.
You can also personalize how the interface will display your DocumentTypes.
Menu section
By default, if you leave this field empty, all Documents will be displayed in the Monitoring section, with
one menu entry by DocumentType.
By using this parameter, you can group multiple DocumentTypes in just one menu section. The DocumentTypes will then be displayed as tabs in this menu section.
To do this, just put here an id of the menu section. All the DocumentTypes with the same id will be
grouped together.
Labels
This parameter allows you to load labels that must be used, in any language, to display data related to this
DocumentType.
To do this, you must load a zip file containing properties file (with all labels) for every language. Files in
the zip must be named documents_[language].properties, or documents.properties for texts to use by default.
By clicking on link "Download file pattern", you can easily get an example file for the properties files, with
all the correct keys already defined.
256
Admin
Figure 5.8. Document Type labels
List default columns
Names of the columns that must be displayed by default in the list of documents, separated by commas.
The names must be the name of a field. 'id', 'creationMoment', 'lastUpdateMoment', 'keepUntil' are also accepted to show the corresponding columns.
If you leave this field blank, the default is to display the columns for all of your fields, and also id and creationMoment.
Order of elements in the list has no impmortance.
Detail columns
How the fields must be displayed in the page with the details of a document.
The value must have the form [Section1]field1,field2[Section2]field4,field3... For better readability,
newLines are also accepted before every section.
If you leave this field blank, the default is to display all the possible fields.
5.2.5. Do I need one or several account environments ?
Channel elements are very flexible and can be copied from one environment to another as long as the user has
access to both environments. Here is some advice for organising work in Babelway if you plan to use more than
a few channels.
257
Admin
You can create a new environment by clicking on "create new environment", and confirm.
Create environments according to your business
If you manage many channels, you may want to group them together to easily manage them. For example, you
may create a different environment for each of your customers to manage them separately. Or you may create a
specific environment dedicated to testing and another one for production.
Create environments according to your user rights
Users rights can be limited to a specific account environment so you may create different environments to limit
user access to a specific set of channels and messages.
Using a test environment for transformation development
Before starting, let's mention that Babelway is managing a single multi-tenant platform. From a Babelway perspective all environments and messages are "production".
However a customer can decide to organise himself in a traditional multi-environment setting.
Create a "test environment" in your account and use it to develop messages and transformation. Once you are
ready to use it, then "promote" to production by simply replacing the element in your production environment.
When importing the element in the production environment, give it a name including a version indicator. ex:
Invoice flatefile My ERP v1.23 or Invoice Carrefour 96A 200900416. All of the previous "production" version
will therefore remain available allowing you to revert changes if required.
For this model to work properly, it is important to do all modifications in the "test environment". There is no
need to keep a copy of the "promoted" version in the test environment. Should you need to work on an old release, simply copy it back from the production environment.
It is also a best practice to include all the production channels in your test environment. This way you will be
able to test your routing rules and metadata substitution in the gateways. Note that you can use a different type
of gateway to make your life simple, for instance use an email or a web gateway instead of a AS2 gateway.
Service provider
There are 3 valid set-ups for a service provider to use Babelway:
• One account per client
• One environment per client in a single account
• One single account/environment
The key differences between these is the billing and the possibility to give access to end-customers. If each
end-customer should receive their Babelway invoice in full transparency, go for one account per client. If each
client should get individual online access to channels and messages but the service provider takes care of the
overall Babelway invoice, go for one environment per client in a single account. If the service provider
provides full outsourcing service to its customers, without giving them any visibility on Babelway, go for one
single account/environment.
Anyway the best practice for the service provider is still to create a test environment in one of these accounts or
in his own.
258
Admin
5.3. Billing
This screen displays a table showing the details of the billing run. The details will depend on the price plan you
have chosen. For instance if you are on a Babelway BUSSINESS account, the billing runs once a month, at the
anniversary of you account creation. Each month, new lines will be added for monthly fee, the extra volume,
extra channels and so on.
Figure 5.9. Billing details
5.4. Users
The table lists all your users.
Figure 5.10.
To manage a given user, you can just open its details by clicking on it.
Add a user
Click on Add a User to add a new user in any role for your account as described in the Add a User chapter.
259
Admin
5.4.1. Add a User
Add a new user and select their role.
From this screen, you can add and invite a new user and select their role on any of your account environments.
Figure 5.11. Add a user
To add a new user, enter their email address and select their role (one of the 3 available ones described above,
"no access" is not available).
If the role is restricted to an environment (channel manager or web gateway user), you should select the environment the new user will be added to otherwise the drop-down list is not available.
Email
The email address to send the invitation.
Access Level
The rights given to the new user.
Invitation text
You can change the Invitation Text if you want. This message will be sent to the new user to request acceptance and activate this option.
Preferred Language
Babelway's interface will be set in this language when your new user logs into the application.
Click on Back command to cancel and go back to previous screen. Click on Send to send this email and invite
the new user.
260
Admin
Note
The new user will be added with his role after accepting this invitation and activates it by clicking on
the link included in the mail within the three days following the date of your invitation sent.
5.4.2. User detail
Manage and edit the details about one of your users.
Figure 5.12.
Rights
In the "Rights" tab you can assing different access levels to the user for the current environment.
261
Admin
Figure 5.13.
There are six different roles available that are described here:
Account Administrator (Full access)
Has full rights over the account (yourself by default).
Channel Manager
Has full rights over alerts/messages/channels functions, but cannot access admin information (user rights,
billing). This type of access is for people who will manage and maintain channels.
Operations
Can view and operate messages or alerts, but can not change configuration of channels. Can edit partners
but not deploy them. Can manage users of this environment. This type of access is for people who will
manage the system but wihtout modifying the channels.
Monitoring
Can view and operate messages or alerts, but can not change configuration of channels. This type of access
is for people who monitor the system.
Read-only monitoring
Can view messages or alerts, but can not change anythings. This type of access is for people who monitor
the system.
Portal user
Portal user will only see documents (invoices, orders, ...) related to some partners. This role is typically for
people from another company that the owner of the account, and that should only be able to see documents
related to this company.
No Access
Has no access to your environment, but you can switch to another role without sending an invitation.
262
6
Miscellanous
This chapter contains some more information, not closely related to the web interface.
6.1. B2B Integration Project Management
When you set up a channel to tranfer data between your system and the external system of your B2B partner,
you must agree on a way to transfer this data. This activity is a project, possibly involving multiple parties:
Your company, your B2B partner, your and their IT integrator, etc.
So, before starting any implementation, even in a test configuration, Babelway recommends that you follow a
project management process such as this one:
1. Agree on project terms
You and your B2B partner should agree on the purpose of collaboration and data to be transferred. This part
should also include the possible financial terms. Some exchanges may even require the writing of contracts.
2. Write specifications
Together with your B2B partner, you should write technical specifications about what is going to be transferred and how (gateway types and configuration, message formats required, mandatory information included in messages, validation processes, test cases definition for project acceptance...)
3. Plan and execute work
Configure and test your channels to meet agreed specifications. The planning should include when your
partner must have resource available, for example, for testing and for acceptance phases.
4. Production and acceptance tests
Once the development and tests are completed, the system is used in production for a trial period. If adjustements are required, they should be implemented as soon as possible. Once all issues are solved and the trial
period is finished, the system can be fully used in production.
Here is a short checklist of items that will be required during development and that sould be agreed between
both sides and included in the specifications:
At account level:
• Details of users who will have access and their respective roles.
• Details of settings including volumes of transactions, price package, expected concurrent volume...
For each channel:
263
Miscellanous
• Details of gateways in and out including external system details, usernames, passwords, certificates... Details
of test environments of external partners prior to moving to production, if relevant.
• Details of messages in and out formats. Both sides should provide several examples of each in and out message types.
• Details of message transformation rules, possible values mapping, exception, mandatory and optional fields...
• Details of routing rules, if relevant.
• Details of in and out message validation rules, if any.
• Details of messages, channels and any other items naming conventions.
• Details of users notifications (success and/or errors).
• Detailed test plan, including acceptance criteria.
6.2. DNS load-balancing
Hosting and redundancy
Babelway infrastructure is hosted externally. Babelway has agreements with 2 hosting providers:
• Combell, a recognised Belgian hosting company. Combell uses several physical premises in Belgium.
Premises have been audited by an independent consultant mandated by Babelway.
• Amazon, a recognized International company and cloud inventor. Babelway subscribes to the Amazon Web
Service (AWS) allowing Babelway access to virtual servers "on-demand". The servers are physically located
in IRELAND and other locations around the world.
To maximise availability and reliability, not only has Babelway contracted with reliable partners on strict
terms, but it has also installed redundancy between its 2 data centres. In the event of downtime of one of the 2
data centres, Babelway can switch all data traffic to the other data centre. Current limitation of the redundancy
are:
• SelfService application (human access to user hubs) are only active on one data center. In case of unavailability of this infrastructure, messaging services can continue but human tracking or maintenance is not available. A manual process allows Babelway to switch the SelfService application to the other infrastructure.
• Gateways to external systems based on physical IP addressing would also be interrupted. We recommend
that users use a URL locator instead of IP addressing wherever possible.
DNS load-balancing and fail-over
Babelway always maintains the configuration of the 2 data centres in sync. All customer configurations are deployed concurrently on both infrastructures. The load balancing and the fail-over between data centres are performed at the DNS level. The messaging engine deployed in the 2 data centres have the ability to work in complete autonomy in both active / active or active / passive modes. This mechanism is used by Babelway for failover as well as scalability needs.
264
Miscellanous
To fully leverage Babelway fail-over mechanism, traffic with Babelway gateways are based on DNS (logical
addressing) and accept traffic with each of the public IP address published by Babelway.
For outbound traffic, Babelway guarantees that all traffic will be issued from one of its public IP addresses.
For inbound traffic, Babelway guarantees that all DNS entries for public services, like ftp.babelway.net,
ws.babelway.net or as2.babelway.net will be resolved to one or several of its public IP addresses. At any time,
DNS will be resolved to 2, 3 or 4 servers. Clients software connecting to Babelway should be able to fail-over
to the next IP in case of a server is unreachable (like all Browsers do). Babelway reserves the right to changes
these allocations.
6.3. External References
Regex or regular expression
Regular expressions provide a concise and flexible means for identifying strings of text of interest, such as particular characters, words, or patterns. A regular expression, or a regex, is written in a formal language that can
be interpreted by a regular expression processor, a program that examines text and identifies parts that match
the provided specification.
Among other sources, you can find a description and a help about Regex on the following website http://www.regular-expressions.info/
XML
XML (Extensible Markup Language) is a set of rules for encoding documents electronically. It is defined in the
XML 1.0 Specification produced by the W3C and several other open standards. XML’s design goals emphasize
simplicity, generality, and usability over the Internet. It is a textual data format.
Although XML design focuses on documents, it is widely used for the representation of arbitrary data structures, for example in EDI transactions. There are a variety of programming interfaces which software developers may use to access XML data. XML has become a wide-used file format.
Among other sources, you can find a description, help and tutorial about XML language on W3Schools website
at http://www.w3schools.com/xml/default.asp
Xslt
XSL Transformations (XSLT) is a declarative XML-based language used for the transformation of XML documents into other XML documents. The original document is not changed and a new document is created based
on the content of the original one.
XSLT is also used to translate XML messages between different XML schemas, or to make changes to documents within the scope of a single schema, for example by removing the parts of a message that are not needed.
Among other sources, you can find a description, help and tutorial about Xslt language on W3Schools website
at http://www.w3schools.com/xsl/default.asp
XPath
265
Miscellanous
XPath, the XML Path Language, is a query language for selecting nodes from an XML document. In addition,
XPath may be used to compute values (e.g., strings, numbers, or Boolean values) from the content of an XML
document.
Among other sources, you can find a description, help and tutorial about XPatch language on W3Schools website at http://www.w3schools.com/xpath/default.asp
EDIFACT
United Nations/Electronic Data Interchange For Administration, Commerce and Transport (UN/EDIFACT) is
the international EDI standard developed under the United Nations.
Among other sources, you can find a description, help and tutorial about EDIFACT on the official website at
http://www.unece.org/trade/untdid/welcome.html
X12
ASC X12, chartered by the American National Standards Institute (ANSI) in 1979, develops EDI standards for
national and global markets.
Among other sources, you can find a description, help and tutorial about X12 on the official website at http://www.x12.org
Odette
Among other sources, you can find a description, help and tutorial about X12 on the official website at http://www.odette.org/html/home.htm
AS2
Among other sources, you can find a description, help and tutorial about AS2 on the following website : http://www.as2basics.co.uk/index.htm
OFTP
Among other sources, you can find a description, help and tutorial about X12 on the official website at http://oftp.net/US/default.htm
FTP
266
Miscellanous
Among other sources, you can find a description, help and tutorial about X12 on the official website at http://www.x12.org
6.4. Rest API
The Rest API provides for third party software developers, a way to access the Babelway data (catalogue
entries, user's channel, user's tickets, user's messages) and integrate them inside of their own application.
For software developers, it is way to easily interact with Babelway directly from within your application. The
API is based on the REST protocol, using the JSON and XML formats.
6.4.1. Introduction
URLs
All
the
requests
to
access
the
REST
api
have
the
form
tps://www.babelway.net/SelfService3/rest/v2/hub-{hubId}/{action}.{format}?{parameters}, where
ht-
hubId
The id of your environment. It can be found in the Environment settings section, under the Admin menu.
format
The format in which you want to receive the answer. It must be 'json' or 'xml'. All actions support the 2
formats.
action and parameters
The name and parameters of the action you want to call. See below for all available actions and parameters.
Authentication
All the requests require authentication.
The API currently supports the HTTP Basic Authentication1.
It is also possible to provide the credentials via the 2 extra parameters userName and pwd
The Babelway Rest API is to be used on a HTTPS (SSL/TLS) connection in order to encrypt the credentials.
Representations
All timestamps should be formatted as the number of milliseconds since the first of January 1970 (midnight
UTC/GMT).
6.4.2. Available actions
The following methods are available in the api:
1
http://en.wikipedia.org/wiki/Basic_access_authentication#Example
267
Miscellanous
6.4.2.1. tickets
This actions allows to list all the tickets, optionnaly filtered by some search criteria.
Parameters
description
A keyword to filter the tickets by. It will search within the description.
status
The status of ticket. The accepted values are OPEN and CLOSED.
severity
The severity of ticket. The accepted values are HIGH, MEDIUM, LOW and INFO.
since
Returns tickets created after the given timestamp.
before
Returns tickets created before the given timestamp.
type
The type of ticket, one in the following list.
The following values are accepted : _0_MONITORING, _1_MESSAGE_PROCESSING_ISSUES,
_1_1_UNIDENTIFIED_SOURCE,
_1_2_UNIDENTIFIED_MESSAGE_IN,
_1_3_UNIDENTIFIED_CHANNEL,
_1_4_MESSAGE_VALIDATION_ISSUE,
_1_5_FAILED_DELIVERY,
_1_6_PLANNED_CLEANING_OF_UNATTENDED_MESSAGES,
_2_HUB_ISSUES,
_2_1_STORAGE_CAPACITY_REACHED,
_2_2_PLANNED_MAINTENANCE_UNAVAILABILITY,
_2_3_NEW_FUNCTIONALITY_AVAILABLE,
_3_ACCOUNT_ISSUES,
_3_1_CREDIT_LIMIT_REACHED,
_3_2_UNPAID_INVOICE,
_3_3_CREDIT_LIMIT_NEAR_REACHED,
_3_4_VAT_CHANGED,
_4_CHANNEL_MANAGEMENT_ISSUE,
_4_1_MAINTENANCE_WARNING_OF_A_LINKED_CHANNEL,
_4_2_PLANNED_DELETION_OF_UNUSED_CHANNELS,
_4_3_DOCUMENTATION_OF_A_CHANNEL,
_4_4_CERTIFICATE_EXPIRATION,
_5_USER_MANAGEMENT_ISSUE,
_5_1_FAILED_CONNECTION_ATTEMPTS,
_5_2_FIRST_CONNECTION_FROM_INVITEE,
_5_3_PLANNED_CLEANING_OF_DORMANT_USERS, _5_4_INVITATION_EXPIRED
start
An integer to set the first result. By default, the value is at 0. The API returns 25 results per query. To get
the 25 next one, it should be 25, then 50, then 75, ...
Examples
• Get tickets with severity MEDIUM in environment 12345 in JSON format
https://www.babelway.net/SelfService3/rest/v2/hub-12345/tickets.json?severity=MEDIUM
[
{
268
Miscellanous
"ticket":222577,
"hub":12345,
"type":"_0_MONITORING",
"severity":"MEDIUM",
"status":"OPEN",
"summary":"Ftp server : ftp:\/\/ftp.server.com\/input DOWN",
"description": "Ftp server (ftp:\/\/ftp.server.com\/input) became DOWN at 07\/02\/2011
"creationMoment":1349180055000,
"key":"aa3a19d7-14f4-4f66-819b-e044eb24b273"
}
]
• Get opened tickets in environment 12345 in XML format
https://www.babelway.net/SelfService3/rest/v2/hub-12345/tickets.xml?status=OPEN
<collection>
<ticket>
<ticket>222577</ticket>
<hub>12345</hub>
<type>_0_MONITORING</type>
<severity>MEDIUM</severity>
<status>OPEN</status>
<summary>Ftp server : ftp://ftp.server.com/input DOWN</summary>
<description>Ftp server (ftp://ftp.server.com/input) became DOWN at 07/02/2011 01:46:3
<creationMoment>1349180055000</creationMoment>
<key>aa3a19d7-14f4-4f66-819b-e044eb24b273</key>
</ticket>
</collection>
6.4.2.2. ticket
This action allows to get all the informations about a ticket.
Parameters
key
the ticket key as found by listing messages
Examples
• Get the details for the ticket with key 'aa3a19d7-14f4-4f66-819b-e044eb24b273' in JSON format
https://www.babelway.net/SelfService/rest/v1/hub-12345/ticket.json?key=aa3a19d7-14f4-4f66-819b-e044eb24
b273
{
"ticket":222577,
"hub":12345,
"type":"_0_MONITORING",
"severity":"MEDIUM",
"status":"OPEN",
"summary":"Ftp server : ftp:\/\/ftp.server.com\/input DOWN",
"description": "Ftp server (ftp:\/\/ftp.server.com\/input) became DOWN at 07\/02\/2011 01:46:3
"key":"aa3a19d7-14f4-4f66-819b-e044eb24b273"
269
Miscellanous
}
6.4.2.3. deleteTicket
This action allows to delete a ticket. It returns true if ticket have been found and deleted, or false otherwise.
Parameters
key
the ticket key
Examples
• Delete the ticket with key 'aa3a19d7-14f4-4f66-819b-e044eb24b273' in JSON format
https://www.babelway.net/SelfService/rest/v1/hub-12345/deleteTicket.json?key=aa3a19d7-14f4-4f66-819b-e0
44eb24b273
"true"
6.4.2.4. messages
Search and list messages.
Parameters
Parameters can be added to filter the query
key
A message key
channel
a string search in the channel name
since
Returns messages created after the given timestamp (number of milliseconds since the first of January
1970, midnight UTC/GMT)
before
Returns messages created before the given timestamp (number of milliseconds since the first of January
gatewayIn
a string search in the gateway in name
gatewayOut
a string search in the gateway out name
270
Miscellanous
maxInSize
the maximum size of the incoming message (in bytes)
minInSize
the minimum size of the incoming message (in bytes)
errorDescription
a string search within the error description
ref
the message reference
status
The status of the message. The accepted values are IN_PROGRESS, PAUSED, IN_DELIVERY, SUCCESS, ERROR, ERROR_CLOSED.
type
The type of ticket. The accepted values are REGULAR and TEST.
start
Examples
• Get regular messages that ended up in success in JSON format in environment 12345
https://www.babelway.net/SelfService3/rest/v2/hub-12345/messages.json?status=DONE&type=REGULAR
[
{
"message":6442207,
"hub":26112,
"key":"5914d53b-cb39-4221-ad0d-42a2af8d487c",
"test":"false",
"testCase":0,
"status":"DONE",
"channel":{"id":66264,"name":"Channel2","type":"Channel","subType":"CHANNEL"},
"gatewayIn":{"id":66292,"name":"EmailBertrand2","type":"Gateway","subType":"GATEWAY_IN
"gatewayOut":{"id":64080,"name":"Email","type":"Gateway","subType":"GATEWAY_OUT_SMTP_O
"reference":"brol.csv",
"longTerm":"false",
"acknowledgmentMoment":null,
"acknowledgmentReference":null,
"errorDescription":null,
"receiveMoment":1330072230000,
"gatewayInMoment":1330072230000,
"gatewayOutMoment":1330072231000,
"gatewayInMessageStatus":"Received from 74.125.82.177 using Smtp In server",
"gatewayInMessageKey":"<[email protected]>",
"gatewayOutMessageKey":null
},
{
"message":6481099,
"hub":26112,
"key":"4c196771-5a93-4d67-b7ac-6c45f9268886",
"test":"false",
"testCase":0,
"status":"DONE",
271
Miscellanous
"channel":{"id":66264,"name":"Channel2","type":"Channel","subType":"CHANNEL"},
"gatewayIn":{"id":66292,"name":"EmailBertrand2",
"type":"Gateway","subType":"GATEWAY_IN_SMTP_IN"},
"reference":"brol.csv",
"longTerm":"false",
"acknowledgmentMoment":null,
"acknowledgmentReference":null,
"errorDescription":null,
"receiveMoment":1330336124000,
"gatewayInMoment":1330336124000,
"gatewayOutMoment":1330336126000,
"gatewayInMessageStatus":"Received from 209.85.214.49 using Smtp In server",
"gatewayInMessageKey":"<[email protected]>",
"gatewayOutMessageKey":null
}
]
6.4.2.5. message
Gets all the informations about a message
Parameters
key
the message key.
Examples
• Get the details for the message with key '5914d53b-cb39-4221-ad0d-42a2af8d487c' in XML format
https://www.babelway.net/SelfService3/rest/v2/hub-26112/message.xml?key=5914d53b-cb39-4221-ad0d-42a2
af8d487c
<messageRecord>
<message>6442207</message>
<hub>26112</hub>
<key>5914d53b-cb39-4221-ad0d-42a2af8d487c</key>
<test>false</test>
<testCase>0</testCase>
<status>DONE</status>
<channel>
<id>66264</id>
<name>Channel2</name>
<type>Channel</type>
<subType>CHANNEL</subType>
</channel>
<gatewayIn>
<id>66292</id>
<name>EmailBertrand2</name>
<type>Gateway</type>
<subType>GATEWAY_IN_SMTP_IN</subType>
</gatewayIn>
<gatewayOut>
<id>64080</id>
<name>Email</name>
272
Miscellanous
<subType>GATEWAY_OUT_SMTP_OUT</subType>
</gatewayOut>
<reference>brol.csv</reference>
<longTerm>false</longTerm>
<acknowledgmentMoment/>
<acknowledgmentReference/>
<errorDescription/>
<receiveMoment>1330072230000</receiveMoment>
<gatewayInMoment>1330072230000</gatewayInMoment>
<gatewayOutMoment>1330072231000</gatewayOutMoment>
<gatewayInMessageStatus>Received from 74.125.82.177 using Smtp In server</gatewayInMessageStat
<gatewayInMessageKey><[email protected]></gatewayInMessageKey>
<gatewayOutMessageKey/>
</messageRecord>
6.4.2.6. channels
You can search and list channels for a given environment.
Parameters
name
A string search on the channel name
description
a string search on the channel description
since
Returns messages created after the given timestamp (number of milliseconds since the first of January
before
Returns messages created before the given timestamp.
deployed
'true' or 'false' : returns channels that are deployed or not (i.e. in production). If not set, the API returns all
channels regardless of their deployed state.
start
Examples
• List the channels of environment 26112 in JSON format
https://www.babelway.net/SelfService3/rest/v2/hub-12345/channels.json
[
{
"id":66264,
"hub":26112,
"lastUpdateMoment":1346405222000,
"name":"Channel2",
"description":"Second test...",
273
Miscellanous
"gatewayIn":{"id":66292,"name":"EmailBertrand2","type":"Gateway","subType":"GATEWAY_IN
"messageDefinitionIn":{"id":66268,"name":"SimpleCsv","type":"MessageDefinition","subTy
"messageDefinitionOut":{"id":66270,"name":"SimpleCsv","type":"MessageDefinition","subT
"transformation":{"id":107807,"name":"k","type":"Transformation","subType":"VISUAL"},
"active":"false",
"deployed":"true",
"nextDeploymentAction":"desactivate"
},
{
"id":106823,
"hub":26112,"creationMoment":1337006265000,
"name":"dgfh",
"description":null,
"gatewayIn":null,
"gatewayOut":{"id":106825,"name":"dfg","type":"Gateway","subType":"GATEWAY_OUT_OFTP2_S
"messageDefinitionIn":{"id":66268,"name":"SimpleCsv","type":"MessageDefinition","subTy
"messageDefinitionOut":{"id":66270,"name":"SimpleCsv","type":"MessageDefinition","subT
"transformation":{"id":106919,"name":"sdf","type":"Transformation","subType":"VISUAL"}
"active":"false",
"deployed":"false",
"nextDeploymentAction":"noChange"
}
]
• List deployed channels in environment 26112 in XML format
https://www.babelway.net/SelfService3/rest/v2/hub-26112/channels.xml?deployed=true
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<collection>
<channel>
<id>66264</id>
<hub>26112</hub>
<lastUpdateMoment>1346405222000</lastUpdateMoment>
<name>Channel2</name>
<description>Second test...</description>
<gatewayIn>
<id>66292</id>
<subType>GATEWAY_IN_SMTP_IN</subType>
</gatewayIn>
<gatewayOut>
<id>64080</id>
<name>Email</name>
<subType>GATEWAY_OUT_SMTP_OUT</subType>
</gatewayOut>
<messageDefinitionIn>
<id>66268</id>
<name>SimpleCsv</name>
<type>MessageDefinition</type>
<subType>CSV</subType>
</messageDefinitionIn>
<messageDefinitionOut>
<id>66270</id>
</messageDefinitionOut>
<transformation>
<id>107807</id>
<name>k</name>
274
Miscellanous
<type>Transformation</type>
<subType>VISUAL</subType>
</transformation>
<active>false</active>
<deployed>true</deployed>
<nextDeploymentAction>desactivate</nextDeploymentAction>
</channel>
</collection>
6.4.2.7. gateways
Search and list gateways for a given environment.
Parameters
name
description
since
Returns only gateways created after the given timestamp.
before
Returns only gateways created before the given timestamp.
direction
Returns only the gateways with the specified direction : IN or OUT.
type
Returns only the gateways with the specified type.
start
Examples
• List all the gateways of environment 26112 in XML format
https://www.babelway.net/SelfService3/rest/v2/hub-26112/gateways.xml
<collection>
<gateway>
<id>106825</id>
<type>GATEWAY_OUT_OFTP2_SERVER_OUT</type>
<name>dfg</name><description/>
<hub>26112</hub>
</gateway>
<gateway>
<id>66292</id>
<type>GATEWAY_IN_SMTP_IN</type>
275
Miscellanous
<description>Emails from [email protected].</description
><hub>26112</hub>
</gateway>
</collection>
• List all the OUT gateways of environment 26112 in JSON format
https://www.babelway.net/SelfService3/rest/v2/hub-26112/gateways.json?direction=IN
[
{
"id":66292,
"type":"GATEWAY_IN_SMTP_IN",
"name":"EmailBertrand2",
"description":"Emails from [email protected].",
"hub":26112
}
]
6.4.2.8. messageDefinitions
Search and list message definitions for a given environment.
Parameters
name
description
since
before
direction
Returns only the gateways with the specified direction : IN or OUT.
type
Returns only the gateways with the specified type.
start
Examples
276
Miscellanous
• List all the messages definitions IN of environment 26112 in JSON format
https://www.babelway.net/SelfService3/rest/v2/hub-26112/messageDefinitions.json?direction=IN
[
{
"id":106869,
"direction":"IN",
"type":"CSV",
"name":"MyOrder",
"description":null,
"hub":26112
}
]
6.4.2.9. transformations
Search and list transformations for a given environment.
Parameters
name
description
since
before
start
Examples
• List all the transformations of environment 26112 in XML format
https://www.babelway.net/SelfService3/rest/v2/hub-26112/transformations.xml
<collection>
<transformation>
<id>106919</id>
<name>SimpleTransformation</name>
<description/><type>VISUAL</type>
<messageDefinitionIn>
<id>66268</id>
</messageDefinitionIn>
<messageDefinitionOut>
277
Miscellanous
<id>66270</id>
</messageDefinitionOut>
<hub>26112</hub>
</transformation>
</collection>
6.4.2.10. catalogue
Search and list catalogue items
Parameters
q
a query string (not case-sensitive)
start
Examples
• Get catalogue items with the tags 'belgium' and 'as2' in JSON
https://www.babelway.net/SelfService3/rest/v2/hub-26112/catalogue.xml?q=belgium%20as2
<collection>
<gateway>
<id>28786</id>
<type>GATEWAY_IN_AS2_IN</type>
<name>AS2 Delhaize</name>
<description>AS2 parameters to exchange files with Delhaize. </description>
<hub>25037</hub>
</gateway>
<gateway>
<id>33967</id>
<type>GATEWAY_IN_AS2_IN</type>
<name>AS2 Cora (Belux)</name>
<description>AS2 Connection to be used in order to receive messages from Cora (Belux).
<hub>25037</hub>
</gateway>
</collection>
6.4.3. Code samples
Here are examples written in different programming language to show how to use the Babelway REST API
within your application. These are just starting points to build upon.
278
Miscellanous
Java
Download the last 25 messages in ERROR. It requires using Apache Commons httpclient2, codec3 and logging4
for HTTP calls and SAX for XML parsing
import java.io.BufferedReader;
import java.io.InputStream;
import java.io.InputStreamReader;
import javax.xml.parsers.SAXParser;
import javax.xml.parsers.SAXParserFactory;
import
import
import
import
import
import
import
org.apache.commons.httpclient.HttpClient;
org.apache.commons.httpclient.UsernamePasswordCredentials;
org.apache.commons.httpclient.auth.AuthScope;
org.apache.commons.httpclient.methods.GetMethod;
org.xml.sax.Attributes;
org.xml.sax.SAXException;
org.xml.sax.helpers.DefaultHandler;
public class RESTClient {
public static void main(String[] args) throws Exception {
String baseUrl = "https://www.babelway.net/SelfService/rest/v1/";
Long myHub = 0L; // You can find this on the My Account page
String user = "";// the username you use to connect to Babelway
String pwd = ""; // the password you use to connect to Babelway
// Download the last 25 messages in ERROR
String request = baseUrl + "hub-" + myHub + "/messages.xml?status=ERROR";
HttpClient client = new HttpClient();
client.getState().setCredentials(AuthScope.ANY_REALM, "www.babelway.net", new UsernamePasswordCreden
GetMethod method = new GetMethod(request);
// Send the request
int statusCode = client.executeMethod(method);
// read the result
if (statusCode == 200) {
InputStream rstream = null;
rstream = method.getResponseBodyAsStream();
BufferedReader br = new BufferedReader(new InputStreamReader(rstream));
SAXParser sxp = SAXParserFactory.newInstance().newSAXParser();
sxp.parse(rstream, new SaxHandler());
}
}
private static final class SaxHandler extends DefaultHandler {
// invoked when document-parsing is started:
public void startDocument() throws SAXException {
System.out.println("Document processing started");
}
// notifies about finish of parsing:
public void endDocument() throws SAXException {
System.out.println("Document processing finished");
}
// we enter to element 'qName':
public void startElement(String uri, String localName,
String qName, Attributes attrs) throws SAXException {
// Do your processing
2
http://hc.apache.org/httpclient-3.x/
http://commons.apache.org/codec/
4
http://commons.apache.org/logging/
3
279
Miscellanous
System.out.println("Element " + qName);
}
// we leave element 'qName' without any actions:
public void endElement(String uri, String localName, String qName)
throws SAXException {
// do nothing;
}
}
}
C#
using
using
using
using
System;
System.Text;
System.Net;
System.IO;
namespace RESTClient
{
class Program
{
static void Main(string[] args)
{
string baseURL = "https://www.babelway.net/SelfService/rest/v1/";
long myHub = 0; // You can find this on the My Account page
String user = "";// the username you use to connect to Babelway
String pwd = ""; // the password you use to connect to Babelway
// Download the last 25 messages in ERROR
String request = baseURL + "hub-" + myHub + "/messages.xml?status=ERROR";
HttpWebRequest webRequest = WebRequest.Create(request) as HttpWebRequest;
// Add authentication to request
webRequest.Credentials = new NetworkCredential(user, pwd);
// Get Response
HttpWebResponse response = webRequest.GetResponse() as HttpWebResponse;
// Read the result
if (webRequest.HaveResponse == true && response != null)
{
// Get the response stream
StreamReader reader = new StreamReader(response.GetResponseStream());
// Console application output
Console.WriteLine(reader.ReadToEnd());
}
}
}
}
Python
This code snipet requires Python 2.6 or newer. No extra modules are required
import json
import urllib2
base_url = "https://www.babelway.net/SelfService/rest/v1/";
my_hub = 0 #You can find this on the My Account page
user = "" #the username you use to connect to Babelway
pwd = "" #the password you use to connect to Babelway
280
Miscellanous
request = "%shub-%s/messages.json" %(base_url, my_hub)
# Create a pwd manager that handles any realm (default realm)
pwd_manager = urllib2.HTTPPasswordMgrWithDefaultRealm()
# Create the authentication handler, add the login/pwd to it
auth_handler = urllib2.HTTPBasicAuthHandler(pwd_manager)
auth_handler.add_password(None, request, user, pwd)
# Build the URL Opener
opener = urllib2.build_opener(auth_handler)
urllib2.install_opener(opener)
# Read and parse the JSON response
try:
f = urllib2.urlopen(request)
print json.load(f)
except urllib2.HTTPError as e:
print e
PHP
This code snippet requires PHP version 5.2.0 or newer. No extra modules are required.
<?
$base_url = "https://www.babelway.net/SelfService/rest/v1/";
$my_hub = 0; // You can find this on the My Account page :
$user = ""; // the username you use to connect to Babelway
$pwd = ""; // the password you use to connect to Babelway
// Download all your tickets for the month of July 2010
$from = mktime(0, 0, 0, 7, 1, 2010);
$to = mktime(23, 59, 59, 7, 31, 2010);
// Generate the URL for the tickets:
$url = $base_url . "hub-" . $my_hub . "/messages.json?since=" . $from . "&before=" . $to;
// Make the REST query
$context = stream_context_create(array(
'http' => array(
'method' => 'GET',
'header' => sprintf("Authorization: Basic %s\r\n", base64_encode($user.':'.$pwd))."\r\n",
'timeout' => 5,
),
));
$content = file_get_contents($url, false, $context);
// Decode the JSON
$data = json_decode($content);
// Display them
echo '<pre>';
print_r($data);
echo '</pre>';
?>
6.5. BabelInvoice
281
Miscellanous
6.5.1. BabelInvoice Solution
BabelInvoice is a solution to send secure electronic invoices. BabelInvoice leverages Babelway's B2B integration in the cloud.
The sender
BabelInvoice enables you to forget the paper invoice all together. It works as a regular printer: The sender
'prints' the invoice on the BabelInvoice printer. The invoice is then automatically sent to the receiver through
Babelway. As the sender of the invoice, you receive an email copy of the invoice sent to your customer. Store it
on your computer and keep a back-up for safety. This invoice is signed with an advanced signature using the
accredited system of Babelway. This method guarantees the authenticity and the integrity of the invoice. At any
time in the future, you can certify and demonstrate the authenticity and the integrity of the invoice.
The receiver
Your customers receive an email with your invoice as a PDF attachment. They can store and print it without the
need to subscribe to Babelway or any other system. The electronic signature generated by Babelway makes the
invoice authentic and unalterable.
The e-invoice
The PDF invoice looks exactly the same as the invoice that would have been printed using your usual printer.
Pictures, logos, fonts, etc. are kept. BabelInvoice also transfers XML information to Babelway. This enables
you to extend BabelInvoice to send any other formats to enable automatic integration, via any protocol, with
accounting software.
The signature
The signature used to sign your invoice is uniquely attached to you. No other Babelway user can sign with this
unique signature. The first time a customer receives an invoice from you, the signature will appear with a yellow question mark.
Figure 6.1. yellow-questionmark
This is to request the customers attention that this document comes with a signature that is not recognized yet.
To accept your signature, your customer must click on the yellow question mark and include your signature in
the list of trusted signatures. Next time, your customer will receive an invoice with a green OK sign (V) to indicate that the invoice is signed by a trusted person.
282
Miscellanous
Figure 6.2. green-v
Note
The advanced signature complies with the definition of Directive 1999/93/CE of the European Parliament and the Council of 13 December 1999.
Archiving
Babelway stores invoices for 3 months (unless you ask otherwise). Archive security elements (guaranteeing the
authenticity and the integrity of your invoices) are kept by Babelway for at least 12 years. This enables, at any
future time, to legally prove that an invoice has been sent through the sender's account at a specific time.
Legal requirements
In Belgium (our country), the law requires that you get explicit approval from your customers to send them
electronic invoices. Sending an email is the most widely accepted method for electronic invoices. Legal requirements may change from country to country, you should seek legal advice if you are unsure.
6.5.2. Install BabelInvoice for PDFCreator
To Install BabelInvoice you should follow these steps:
Pre Requirements
BabelInvoice for PDFCreator require the following software
1-.Net framework 3 or above.
2- PDFCreator version 1.0.0 or above.
If you didn’t install the required software before running the installation the setup will detect the missing requirement and download it after confirming that is your choice.
Installation
1-After clicking on the exe file you will see the welcome screen, click on "Next".
283
Miscellanous
Figure 6.3. BabelInvoice Setup Wlcom Screen
2-The setup will check the required software and inform you of any missing software , click on "OK" to download and install it or cancel the setup and install it from any other location.
Figure 6.4. BabelInvoice Missing Software Dialog
If you chose to download the required software the download screen will appear and download will start immediately.
284
Miscellanous
Figure 6.5. BabelInvoice Download Screen
After finishing download you should install the software with you requirements.
3- Select the destination folder you want to install application in and click "Next".
285
Miscellanous
Figure 6.6. BabelInvoice Select Install Location
4-Setup will install the files to the selected destination.
286
Miscellanous
Figure 6.7. BabelInvoice Installation Process
5-Application needs to create new printer on PDFCreator printer, click "Next" to create it.
287
Miscellanous
Figure 6.8. BabelInvoice Add Printer
6-Click on Finish to complete the setup process
288
Miscellanous
Figure 6.9. BabelInvoice Finish Setup
7-After finishing the setup process you need to verify that the created printer is assigned properly with the right
profile to allow BabelInvoice work properly.
Open PDFCreator printers screen from PDFCreator->Printer->Printers.
Make sure that printer "BabelInvoice (PDFCreator)" is assigned to the profile "BabelInvoice".
289
Miscellanous
Figure 6.10. Assign the printer with the profile
8-You can use the BabelInvoice for PDFCreator by printing the documents with the created printer.
290
Miscellanous
Figure 6.11. BabelInvoice Printing Document
After printing the document you will see the main screen of the BabelInvoice application, type the required
parameter and send the document.
291
Miscellanous
Figure 6.12. BabelInvoice Email Form
6.5.3. Using BabelInvoice for Stand alone
BabelInvoice for Standalone version designed for use by command prompt.
After installing the package you can use it by calling the BabelInvoice.exe with the following parameters
292
Miscellanous
Figure 6.13. BabelInvoice for Standalone
-Help
Show list of available commands.
"Input File"
The invoice file path.
-User="UserName"
Set the FTP User (OPTIONAL).
-M"%metadata name%"="%Value%"
Add metadata to metadata.xml (OPTIONAL).
-Silent
Don’t show any error messages and write the error details in the log file and return exit code (OPTIONAL).
-Settings
Open the settings form (OPTIONAL).
-Config
Sets the configuration folder path (create if not exists), (OPTIONAL) default folder is Application Data
folder.
6.5.4. BabelInvoice Setting
To set up your BabelInvoice you should follow these steps:
1- Babelway Registration
If you don't have an account yet, please register at http://www.babelway.net
293
Miscellanous
2- Babelway Channel Import
You should Import the BabelInvoice Channel to your Babelway Account. If you don’t have a channel yet,
please
import
the
BabelInvoice
to
your
hub
by
clicking
on
this
link
http://www.babelway.net/i/ZTQwNTg3/BabelInvoice_1.5_using_email_form.
3- Configure FTP gateway in
You only need to set username and password for the input ftp gateway in, you will need these parameters in the
BabelInvoice application. Don't forget to save after setting the username and password.
Figure 6.14. BabelInvoice FTP In
To read more about ftp server gateway configuration click here
4- Activate and Deploy the channel
First activate the channel you've just imported by clicking on the "Activate channel" button on the top right of
the screen. Then deploy by clicking on "Deploy channel" at the bottom of the list of channels.
Figure 6.15. BabelInvoice activate channel
294
Miscellanous
Figure 6.16. BabelInvoice Deploy channel
To read more about Activate and Deploy a Channel click here
5- Configure BabelInvoice application
The first time you'll use the BabelInvoice application, the setting screen will appear. It will let you configure
the application with your parameters.
295
Miscellanous
Figure 6.17. BabelInvoice Settings
6.6. Verify yourself the chain
296
Miscellanous
To verify the message yourself, you will need 3 set of files. First you need the secure chain chunk containing
the message, then you need the corresponding timestamps and finally the signatures of all messages in the
chunk.
The following java code, using bouncycastle and CSVReader can be use to validate the chain. Please note that
several formats were used successively by Babelway and must be reflected in the validation program.
package com.babelway.business.securechain;
import
import
import
import
import
import
import
import
import
import
import
import
java.io.File;
java.io.FileInputStream;
java.io.InputStreamReader;
java.security.MessageDigest;
java.security.cert.CertStore;
java.security.cert.X509Certificate;
java.text.SimpleDateFormat;
java.util.Collection;
java.util.regex.Matcher;
java.util.regex.Pattern;
java.util.zip.ZipEntry;
java.util.zip.ZipInputStream;
import
import
import
import
import
import
import
import
import
import
import
import
import
import
org.bouncycastle.asn1.ASN1Sequence;
org.bouncycastle.asn1.DERObject;
org.bouncycastle.asn1.DERObjectIdentifier;
org.bouncycastle.asn1.cms.Attribute;
org.bouncycastle.asn1.ocsp.BasicOCSPResponse;
org.bouncycastle.cms.CMSSignedData;
org.bouncycastle.cms.SignerInformation;
org.bouncycastle.jce.provider.BouncyCastleProvider;
org.bouncycastle.ocsp.BasicOCSPResp;
org.bouncycastle.ocsp.CertificateStatus;
org.bouncycastle.ocsp.SingleResp;
org.bouncycastle.tsp.TimeStampToken;
org.bouncycastle.util.encoders.Base64;
org.bouncycastle.util.encoders.Hex;
import au.com.bytecode.opencsv.CSVReader;
import com.babelway.business.common.TestInOneEmptyHub;
import com.babelway.messaging.storage.StoreUtils;
public class SecureChainValidation extends TestInOneEmptyHub {
public static void main(String[] args) throws Exception {
validateSecureChainChunk(new File("..."), new File("..."), new File("..."));
}
private static void validateSecureChainChunk(File secureChainChunkFile, File secureChainChunkT
Pattern messageKeyPattern = Pattern.compile("/Accounts/Account-.*/Hubs/Hub-.*/Messages
ZipInputStream secureChainChunkFileZipInputStream = new ZipInputStream(new FileInputSt
secureChainChunkFileZipInputStream.getNextEntry();
CSVReader secureChainChunkFileReader = new CSVReader(new InputStreamReader(secureChain
ZipInputStream secureChainChunkTimestampsZipInputStream = new ZipInputStream(new FileI
secureChainChunkTimestampsZipInputStream.getNextEntry();
CSVReader secureChainChunkTimestampsReader = new CSVReader(new InputStreamReader(secur
try {
//1. validate timestamps
String[] firstTimestamp = secureChainChunkTimestampsReader.readNext();
String[] lastTimestamp = secureChainChunkTimestampsReader.readNext();
String firstChainId = firstTimestamp[10];
validateTimestampCms(firstTimestamp[3].getBytes(), true, false);
String lastChainId = lastTimestamp[10];
validateTimestampCms(lastTimestamp[3].getBytes(), true, false);
297
Miscellanous
//2. validate chain
//2.a verify the first timestamps
String[] previousSecureChainElement = secureChainChunkFileReader.readNext();
if (!firstChainId.equals(previousSecureChainElement[0])) {
throw new RuntimeException("First timestamp do not match with securech
}
String[] currentSecureChainElement = secureChainChunkFileReader.readNext();
while (previousSecureChainElement != null && currentSecureChainElement != null
//2.b verify the chain
validateChainHash(currentSecureChainElement, previousSecureChainElemen
//2.c verify signatures
Matcher matcher = messageKeyPattern.matcher(currentSecureChainElement[
matcher.matches();
String fileName = matcher.group(1) + "_" + matcher.group(2).toLowerCas
ZipInputStream zis = new ZipInputStream(new FileInputStream(secureChai
ZipEntry entry;
boolean found = false;
while ((entry = zis.getNextEntry()) != null) {
if (entry.getName().equals(fileName)) {
MessageDigest md = MessageDigest.getInstance("SHA-512"
if (!new String(Hex.encode(md.digest(StoreUtils.getByt
throw new RuntimeException("Signature do not m
}
found = true;
break;
}
}
if (!found) {
throw new RuntimeException("Missing signature");
}
previousSecureChainElement = currentSecureChainElement;
currentSecureChainElement = secureChainChunkFileReader.readNext();
}
//2.a verify the last timestamps
if (!lastChainId.equals(previousSecureChainElement[0])) {
throw new RuntimeException("Last timestamp do not match with securecha
}
} finally {
secureChainChunkFileReader.close();
secureChainChunkTimestampsReader.close();
}
}
private static void validateChainHash(String[] secureChainElement, String previousChainHashAsH
SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss.SSS");
String previousChainHash = null;
String signatureHash = null;
String linkedId = null;
if (secureChainElement[9].equals("SCv1")) {
linkedId = secureChainElement[1];
signatureHash = new String(Base64.encode(secureChainElement[7].getBytes()), "U
previousChainHash = new String(Base64.encode(Hex.decode(previousChainHashAsHex
} else if (secureChainElement[9].equals("SCv2")) {
signatureHash = org.postgresql.util.Base64.encodeBytes(secureChainElement[7].g
previousChainHash = org.postgresql.util.Base64.encodeBytes(Hex.decode(previous
previousChainHash = previousChainHash.replaceAll("\n", "\\\\012");
} else if (secureChainElement[9].equals("SCv3")) {
signatureHash = secureChainElement[7];
previousChainHash = previousChainHashAsHex;
} else {
throw new RuntimeException("chain format not supported");
}
StringBuilder sb = new StringBuilder();
sb.append(linkedId).append(';').append(sdf.parse(secureChainElement[2]).getTime()).app
298
Miscellanous
MessageDigest md = MessageDigest.getInstance("SHA-512");
boolean r = new String(Hex.encode(md.digest(sb.toString().getBytes())), "UTF8").equals
if (!r) {
throw new RuntimeException("chain not ok at " + secureChainElement[0] + " s ="
}
}
@SuppressWarnings("unchecked")
private static void validateTimestampCms(byte[] bytes, boolean validateTimestamp, boolean vali
DERObjectIdentifier ID_CONTENT_TYPE = new DERObjectIdentifier("1.2.840.113549.1.9.3");
DERObjectIdentifier ID_MESSAGE_DIGEST = new DERObjectIdentifier("1.2.840.113549.1.9.4"
DERObjectIdentifier ID_SIGNING_TIME = new DERObjectIdentifier("1.2.840.113549.1.9.5");
DERObjectIdentifier ID_SIGNATURETIMESTAMPTOKEN = new DERObjectIdentifier("1.2.840.1135
DERObjectIdentifier ID_COMPLETEREVOCATIONREFERENCES = new DERObjectIdentifier("1.2.840
CMSSignedData signedData = new CMSSignedData(Hex.decode(bytes));
signedData.getSignedContent().getContent();
Collection<SignerInformation> signers = signedData.getSignerInfos().getSigners();
SignerInformation signer = (SignerInformation) signers.iterator().next();
CertStore signedDataCertStore = signedData.getCertificatesAndCRLs("Collection", Bouncy
X509Certificate signingCertificate = (X509Certificate) signedDataCertStore.getCertific
if (!signer.verify(signingCertificate.getPublicKey(), BouncyCastleProvider.PROVIDER_NA
throw new RuntimeException("Signature is not OK");
}
signer.getSignedAttributes().get(ID_SIGNING_TIME).getAttrValues().getObjectAt(0).getDE
signer.getSignedAttributes().get(ID_CONTENT_TYPE).getAttrValues().getObjectAt(0).getDE
signer.getSignedAttributes().get(ID_MESSAGE_DIGEST).getAttrValues().getObjectAt(0).get
if (validateTimestamp) {
TimeStampToken timeStampToken = null;
for (SignerInformation signerInformation : signers) {
Attribute attribute = signerInformation.getUnsignedAttributes().get(ID
if (attribute != null) {
byte[] timestampBytes = attribute.getAttrValues().getObjectAt(
CMSSignedData cmsSignedData = new CMSSignedData(timestampBytes
timeStampToken = new TimeStampToken(cmsSignedData);
}
}
if (timeStampToken != null) {
SignerInformation timestampSigner = (SignerInformation) timeStampToken
CertStore timestampCertStore = timeStampToken.getCertificatesAndCRLs("
X509Certificate timestampSigningCertificate = (X509Certificate) timest
if (!timestampSigner.verify(timestampSigningCertificate.getPublicKey()
throw new RuntimeException("Timestamp status is not OK");
}
} else {
throw new RuntimeException("No timestamp found");
}
}
if (validateOcsp) {
BasicOCSPResp basicResponse = null;
for (SignerInformation signerInformation : signers) {
Attribute attribute = signerInformation.getSignedAttributes().get(ID_C
if (attribute != null) {
DERObject derObject = attribute.getAttrValues().getObjectAt(0)
basicResponse = new BasicOCSPResp(new BasicOCSPResponse((ASN1S
}
}
if (basicResponse != null) {
SingleResp singleResp = basicResponse.getResponses()[0];
if (singleResp.getCertStatus() != CertificateStatus.GOOD) {
throw new RuntimeException("OCSP status is not OK");
}
} else {
throw new RuntimeException("No ocsp found");
}
}
299
Miscellanous
}
}
300

Pdf file - Babelway

Transcription

Similar documents

Strategies for Infusing Global Concepts and Content into the K

Case Study: GateWay Community College

on Visionet Modem M625N Installation Guide

2012_3015_PR_VITEG_conf _Product 23

Driven Experiences Gateway Canyons

La Boutique

Brochure 1 - SOWEGA Council on Aging

NetEdge - Gilat Satellite Networks

GSM Gateway – ProLine-Digital