Docstoc

TRAXi3 - 10009 - Highway - HOW TO - Get Highway to Acknowledge Messages

Document Sample
TRAXi3 - 10009 - Highway - HOW TO - Get Highway to Acknowledge Messages Powered By Docstoc
					HOW TO: Get Highway to Acknowledge Messages
Standard Work Instructions                         How to Get Highway to Acknowledge Messages



 Precision Software Limited



Precision software products are copyrighted and all rights are reserved by Precision Software
Limited.

This document is copyrighted and all rights are reserved. No part of this document may be
reproduced, transmitted, adapted, translated or electronically stored without the prior written
consent of Precision Software Limited.

TRAXi3  i3ship  i3trade  i3comply  and XM4  and are registered trademarks of
Precision Software Limited.
Progress  is a registered trademark of Progress Software Corporation.

Precision Software Limited shall not be liable for errors contained herein or for incidental or
consequential damage or loss in connection with the use of this document. Whilst every effort is
made to eliminate errors, Precision Software Ltd. cannot be held liable for erroneous information
contained herein.




www.precisionsoftware.com                                                              Page 2 of 20
Standard Work Instructions                  How to Get Highway to Acknowledge Messages




Document Control


Issue Control
Issue          Date           Changes Made
1.0            11 Nov 05      Created
1.1            05 April 06    Formatting Change
1.2            20 Apr 06      Review




Cross Reference




Change Summary
Nr.       Description                              Date         By whom
1         Created                                  17/11/05
2         Formatting Change                        05/04/06     Katie Hart
3         Review                                   20/04/06     Ger Harrigan




www.precisionsoftware.com                                                      Page 3 of 20
Standard Work Instructions                                               How to Get Highway to Acknowledge Messages




Contents
PRECISION SOFTWARE PRODUCTS ARE COPYRIGHTED AND ALL RIGHTS ARE
RESERVED BY PRECISION SOFTWARE LIMITED. .....................................................................2
 Document Control ........................................................................................................................ 3
      Issue Control ..........................................................................................................................3
      Cross Reference ....................................................................................................................3
      Change Summary ..................................................................................................................3
 Introduction .................................................................................................................................. 5
    Important Technical Note: ..................................................................................................... 5
 Case 1 Setup ............................................................................................................................... 6
      Input Endpoint ........................................................................................................................6
      Acknowledge Message Type .................................................................................................7
      Acknowledge Endpoint ..........................................................................................................8
      Rule Setup .............................................................................................................................9
 Case 2 Setup ............................................................................................................................. 10
      Output Endpoint .................................................................................................................. 10
      Acknowledge Endpoint ....................................................................................................... 10
      Rule Setup .......................................................................................................................... 11
 Case 3 Setup ............................................................................................................................. 12
      Acknowledge Endpoint ....................................................................................................... 12
      Define an “ACKNOWLEDGE3” Target in cTRAX .............................................................. 12
      Configure Highway ............................................................................................................. 13
 HTTP Note ................................................................................................................................. 16
 Acknowledge File Name Note .................................................................................................... 16
 Appendix A ................................................................................................................................. 17
      Sample XML File ................................................................................................................ 17
      Sample XSL File ................................................................................................................. 18
 Appendix B ................................................................................................................................. 19
 Suggestions for Improved Documentation ................................................................................. 20




www.precisionsoftware.com                                                                                                     Page 4 of 20
Standard Work Instructions                       How to Get Highway to Acknowledge Messages




Introduction
This is a standard work instruction on how to Get Highway to provide the following
acknowledgement functionality:

Acknowledge the fact that a message has been…

    1. Picked up by Highway
    2. Queued for processing by bTRAX
    3. Picked up by the Listener process




Important Technical Note:
The Highway database schema has changed. If applying this change to a 2.5 or earlier
version of the Highway database, you need to execute the following SQL against the
Highway database:

ALTER TABLE ENDPOINT ADD COLUMN ACKMETHOD VARCHAR(10)
UPDATE ENDPOINT SET ACKMETHOD=' '
ALTER TABLE ENDPOINT ADD COLUMN ACKDRIVER VARCHAR(80)
UPDATE ENDPOINT SET ACKDRIVER=' '
ALTER TABLE ENDPOINT ADD COLUMN ACKID VARCHAR(20)
UPDATE ENDPOINT SET ACKID=' '
ALTER TABLE ENDPOINT ADD COLUMN ACKSTEP INTEGER
UPDATE ENDPOINT SET ACKSTEP=0
ALTER TABLE ENDPOINT ADD COLUMN ACKLISTENERPROGRAM VARCHAR(80)
UPDATE ENDPOINT SET ACKLISTENERPROGRAM=' '
ALTER TABLE ENDPOINT ADD COLUMN ACKLISTENERTARGET VARCHAR(80)
UPDATE ENDPOINT SET ACKLISTENERTARGET=' '

One way of doing this is to use the “Manage Highway Database” admin utility.




www.precisionsoftware.com                                                            Page 5 of 20
Standard Work Instructions                     How to Get Highway to Acknowledge Messages



Case 1 Setup
In this case, we want to acknowledge the fact that a message has been picked up from an
endpoint by Highway.

The setup involved is illustrated by configuring Highway so that when a message is read from a
Folder, an acknowledgment message is created and written to an acknowledgement folder. While
the example uses folders, it could just as easily use JMS queues, FTP directories, etc.


Input Endpoint
Create a new input endpoint “MSG_IN1” that will Highway will use to read messages from a
Folder:




www.precisionsoftware.com                                                        Page 6 of 20
Standard Work Instructions                      How to Get Highway to Acknowledge Messages



   In order to get Highway to acknowledge receipt of messages read from this endpoint, you
   need to set the following endpoint fields for “MSG_IN1”:

      Acknowledge Step:
             Flag this as TRUE

      Acknowledge Method:
             Set this to “XSLT”

      Acknowledge Id:
             Set this to “ACKNOWLEDGE1”. This id can be used to setup a rule which will tell
             Highway where to write the acknowledgement message

      Acknowledge Driver:
             Set this to the full path and filename of a XSL file that will convert the message
             read in to an acknowledgement XML file

   See Appendix A for an example message and xsl file.


Acknowledge Message Type
Add an “ACKNOWLEDGE1” Message Type definition to Highway

Give the Message Type an Id of “ACKNOWLEDGE1” and give it a Payload of “TEXT”. This can
be seen in the following screenshot:




www.precisionsoftware.com                                                           Page 7 of 20
Standard Work Instructions                    How to Get Highway to Acknowledge Messages


Acknowledge Endpoint
   Add an “ACKNOWLEDE1” Endpoint definition to Highway.

   Define an acknowledge endpoint in Highway. This endpoint should be of type output. Select a
   suitable means of storage, in this case “Folder”. The screenshot below is defined to put
   acknowledgment messages in the directory “c:\acknowledge1”:




www.precisionsoftware.com                                                        Page 8 of 20
Standard Work Instructions                 How to Get Highway to Acknowledge Messages


Rule Setup
Add a new rule that maps the message id “ACKNOWLEDGE1” to the endpoint
“ACKNOWLEDGE1”:




www.precisionsoftware.com                                                 Page 9 of 20
Standard Work Instructions                      How to Get Highway to Acknowledge Messages




Case 2 Setup
In this case, we want to acknowledge the fact that a message has been written by Highway to an
endpoint.

The setup involved is illustrated by configuring Highway so that when a message is written to a
Folder, an acknowledgment message is created and written to an acknowledgement folder. While
the example uses folders, it could just as easily use JMS queues, FTP directories, etc.


Output Endpoint
   Create a new output endpoint “MSG_OUT” that will Highway will use to write messages to a
   Folder:




Acknowledge Endpoint
Add an “ACKNOWLEDE2” Endpoint definition to Highway (similar to “ACKNOWLEDGE1” added
in case 1).

Define an acknowledge endpoint in Highway. This endpoint should be of type output. Select a
suitable means of storage, in this case “Folder”. The directory for example could be
“c:\acknowledge2”: (overleaf)



www.precisionsoftware.com                                                        Page 10 of 20
Standard Work Instructions                  How to Get Highway to Acknowledge Messages




Rule Setup
Add a new rule that maps the message id “ACKNOWLEDGE2” to the endpoint
“ACKNOWLEDGE2”.


When messages are read from MSG_OUT, acknowledgement will be written to endpoint
ACKNOWLEDGE2.




www.precisionsoftware.com                                                  Page 11 of 20
Standard Work Instructions                      How to Get Highway to Acknowledge Messages




Case 3 Setup
In case 3, the acknowledgement is handled by the listener. An endpoint can be configured with
additional listener acknowledgement details that will allow the listener to send an
acknowledgement message. The listener will depend on a custom plug-in program that will
understand the type of message being received and construct the acknowledgment message.


Acknowledge Endpoint
Add an “ACKNOWLEDGE3” Endpoint Definition to Highway

Define an acknowledge endpoint in Highway. This endpoint should be of type output. Select a
suitable means of storage. The screenshot below is defined to put acknowledgment messages in
the directory “c:\acknowledge3”:




Define an “ACKNOWLEDGE3” Target in                      cTRAX
Highway Targets are defined for cTRAX using the “HIGHWAY” system values. A new target
should be added that maps the “Acknowledgement Target” code to an endpoint in Highway. It is
recommended that the target name and endpoint id be the same.



www.precisionsoftware.com                                                         Page 12 of 20
Standard Work Instructions                       How to Get Highway to Acknowledge Messages



The “Endpoint Target” is the “Listener Acknowledge Target” code defined in Highway that is
associated with the physical queue that the listener is listening to.

The “Endpoint Id” is the endpoint defined in Highway for which acknowledge messages should be
queued.




                                                         Endpoint Target




                                                                   Endpoint Id




Configure Highway
Configure Highway so acknowledgment messages are generated by the listener.

The endpoint which represents the final destination for messages before they are picked up by
the listener needs to be updated with two new endpoint attributes:

Listener Acknowledge Program/Service:
This field holds the name of the program that will be called prior to actually processing the
message in cTRAX. It will examine the message and construct a suitable acknowledgement
message.

Note: this program is a custom program that understands the content of the message and should
be developed as part of any customer services project work.

        Example: xtackmsg.p

Listener Acknowledge Target:
This field holds the target that will be used so the listener can send acknowledgement messages
back to Highway.

        Example: ACKNOWLEDGE3



(Screenshot overleaf)




www.precisionsoftware.com                                                           Page 13 of 20
Standard Work Instructions   How to Get Highway to Acknowledge Messages




                              Information used by Listener




www.precisionsoftware.com                                    Page 14 of 20
Standard Work Instructions                      How to Get Highway to Acknowledge Messages


Technical Note: The parameters for any cTRAX acknowledgement plug-in program are as
follows:

    input – message as memptr
    input – dummy parameter as char (For future use)
    output – acknowledgement as char


A sample skeleton plug-in program is listed below:

/*
 * Sample Acknowledge Plug-in Program
 */

def input parameter pr-message-memptr    as memptr               no-undo.
/* Message we are going to acknowledge receipt of.               */
def input parameter pr-dummy-parameter as char                   no-undo.
/* Not currently used - for possible future needs.               */
def output parameter pr-ack-message      as char                 no-undo.
/* Return path for acknowledge message.                          */
def var wv-acknowledge-message as char no-undo.

/* 1. Examine the message - pr-message-memptr ... */

/** ADD YOUR CODE HERE **/

/* 2. Construct an acknowledge message ... */

/** ADD YOUR CODE HERE **/
assign wv-acknowledge-message = "<?xml version=~"1.0~" encoding=~"UTF-
8~"?>" +
                                "<Acknowledge>" +
                                " <Step>RECEIVED BY LISTENER</Step>" +
                                "
<MessageReference>1234567890</MessageReference>" +
                                "</Acknowledge>".

/* 3. Return this acknowledge message to the Highway Listener ... */
assign pr-ack-message = wv-acknowledge-message.

return.


    A new program “xthwlack.p” has been written in cTRAX. This program handles the new
    listener acknowledgement functionality.




www.precisionsoftware.com                                                     Page 15 of 20
Standard Work Instructions                           How to Get Highway to Acknowledge Messages



HTTP Note
New functionality which allows an acknowledgement in the “CGI” layer for HTTP Posts/Gets has
been added to Highway (v2.9). For a Highway asynchronous process, if “Acknowledge id” for the
target “Endpoint" is set to “*HTTP”, and “Acknowledge driver” set to a driver source location
(currently, it is a xsl file for xslt), the program will first try to acknowledge an incoming well-formed
xml message to its response. If this is not configured, the program will secondly send a response
of “Message Accepted by Highway”

If Highway cannot write the message to an endpoint, a reply of “Message Unaccepted By
Highway” will be returned.




Acknowledge File Name Note
Acknowledge file name by default will be the same name as the file name to be acknowledged.
To append a prefix to an acknowledge file name, a value pair in Highway Setting should be set to:

Seting Id: ACKNOWLEDGE_FILE_PREFIX
Value:     [text]
Appendix A:




www.precisionsoftware.com                                                                 Page 16 of 20
Standard Work Instructions          How to Get Highway to Acknowledge Messages



Appendix A
Sample XML File
<?xml version="1.0" encoding="UTF-8"?>
<rsm:CombinedMaster xmlns:xsd="http://www.w3.org/2001/XMLSchema"

xmlns:rsm="urn:un:unece:uncefact:data:specification:CombinedMaster:1:0"

xmlns:udt="urn:un:unece:uncefact:data:specification:UnqualifiedDataTypes
SchemaModule:1:0"

xmlns:qdt="urn:un:unece:uncefact:data:specification:QualifiedDataTypeSch
emaModule:1:0"

xmlns:ram="urn:un:unece:uncefact:data:specification:ReusableAggregateBus
inessInformationEntitySchemaModule:1:0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:schemaLocation="urn:un:unece:uncefact:data:specification:CombinedMas
ter:1:0 ../maindoc/CombinedMaster-1.0.xsd">
  <rsm:Header>
    <ram:FilenameID>H4080</ram:FilenameID>
    <ram:CreationDateTime>H4090H4100</ram:CreationDateTime>
    <ram:FileTypeCode>H4110</ram:FileTypeCode>
    <ram:TransactionTypeCode>H4150</ram:TransactionTypeCode>
    <ram:Client>
      <ram:DivisionID>H4120</ram:DivisionID>
      <ram:SystemID>H4130</ram:SystemID>
      <ram:LocationID>H4140</ram:LocationID>
      <ram:Reference1ID>H4160</ram:Reference1ID>
      <ram:Reference2ID>H4170</ram:Reference2ID>
      <ram:Reference3ID>H4180</ram:Reference3ID>
      <ram:Reference4ID>H4190</ram:Reference4ID>
      <ram:Reference5ID>H4200</ram:Reference5ID>
    </ram:Client>
  </rsm:Header>
  <rsm:Order>
    <ram:OtherID>H1270</ram:OtherID>
    <ram:DespatchDateTime>H0930</ram:DespatchDateTime>
    <ram:TotalAmount amountCurrencyID="H0850">H3340</ram:TotalAmount>
    <ram:SellerRepresentativeID>H3030</ram:SellerRepresentativeID>
    <ram:SellerRepresentativeID>H3040</ram:SellerRepresentativeID>
    <ram:SellerRepresentativeID>H3050</ram:SellerRepresentativeID>
    <ram:SellerRepresentativeID>H3060</ram:SellerRepresentativeID>
  </rsm:Order>
</rsm:CombinedMaster>




www.precisionsoftware.com                                         Page 17 of 20
Standard Work Instructions          How to Get Highway to Acknowledge Messages


Sample XSL File
<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="2.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:fo="http://www.w3.org/1999/XSL/Format"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:fn="http://www.w3.org/2005/02/xpath-functions"
xmlns:xdt="http://www.w3.org/2005/02/xpath-datatypes"

xmlns:rsm="urn:un:unece:uncefact:data:specification:CombinedMaster:1:0"

xmlns:ram="urn:un:unece:uncefact:data:specification:ReusableAggregateBus
inessInformationEntitySchemaModule:1:0"
>

<xsl:template match="/">

<acknowledgementid>
  <xsl:value-of select="/rsm:CombinedMaster/rsm:Header/ram:FilenameID"/>
</acknowledgementid>

</xsl:template>

</xsl:stylesheet>




www.precisionsoftware.com                                         Page 18 of 20
Standard Work Instructions                      How to Get Highway to Acknowledge Messages



Appendix B
XSL File that creates an acknowledgement XML message for a Compliance Request input
message:

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="2.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
      xmlns:javaDateReader="com.precisionsoftware.highway.xsl.DateFormatter"
      xmlns:javaAcknowledge="com.precisionsoftware.highway.xsl.Acknowledge">

  <xsl:output method="xml"/>

  <xsl:template match="/">
    <AcknowledgeComplianceRequest>
      <ApplicationArea>
        <Sender>
          <LogicalId>Highway</LogicalId>
          <ReferenceId>HighwayR</ReferenceId>
          <UniqueMessageId>ACK:<xsl:value-of
select="javaAcknowledge:getAcknowledgementId()"/></UniqueMessageId>
        </Sender>
        <CreationDateTime>
          <xsl:value-of select="javaDateReader:getDateTime('COMPLETE-TOTAL')"/>
        </CreationDateTime>
      </ApplicationArea>
      <DataArea>
        <Acknowledge confirm="Always"/>
        <ComplianceRequest><xsl:copy-of
select="/ProcessComplianceRequest/DataArea/ComplianceRequest/References"/>
          <RequestStatus>ACCEPTED</RequestStatus>
          <RequestDateTime>
            <xsl:value-of select="javaDateReader:getDateTime('COMPLETE-TOTAL')"/>
          </RequestDateTime>
        </ComplianceRequest>
      </DataArea>
    </AcknowledgeComplianceRequest>
  </xsl:template>
</xsl:stylesheet>


This xsl file will output a new Acknowledgement Compliance Request XML file. It reads in the
process request xml file, gets information from it, produces a unique acknowledgement Id, and
the date and time that the file was created.

It generates the unique acknowledgement id by calling the getAcknowledgementId() method
that produces a unique number every time.

The date is produced by calling another method getDateTime() that gets the system time that
the file was created and formats it to conform to the ISO 8601 standard for date formatting
recognised universally.

Note: This requires Highway 2.10 or later.




www.precisionsoftware.com                                                         Page 19 of 20
Standard Work Instructions                     How to Get Highway to Acknowledge Messages




Suggestions for Improved Documentation
Please report any suggestions that you feel would improve Precision’s documentation and return
via Email: education@precisionsoftware.com.




www.precisionsoftware.com                                                        Page 20 of 20

				
DOCUMENT INFO
Shared By:
Categories:
Tags:
Stats:
views:3
posted:2/6/2011
language:English
pages:20