EDM for Sage X3

Web-Services

Assumptions

For the purposes of this section, the following assumptions are made:

• Engineer has good working knowledge of the general concepts of the Sage X3 development life cycle and functions relating to it
• Engineer has attended the V1 Training course for EDM for Sage X3
• You have browser access / an adminstrative login to Sage X3

Overview

The EDM for Sage X3 solution has always been fully web-service driven.
Over time, these web-services have evolved to enhance the solution as new capability has been added.
The following documents how they are managed.

There are 2 basic concepts, lookups to request data and commits to add data to the Sage X3 database.

All of the following content is provided in the EDM / PIA for Sage X3 patches applied during installation.

Lookups

A lookup is a request for data from Sage X3.

It consists of 3 main elements:

• 4GL
      • This is the ‘code’ to process the request, written in Sage X3’s native language 4GL in an editor such as eclipse and accessible using the native script editor (ADOTRT)

• Sub-Program
      • This is the link between the 4GL and the external web-service. It instructs the web-service what type of data, the fields the 4GL uses and defines the maximum number of results in the form of a dimension (GESASU)

• Web-Service definition
      • This is the externally facing SOAP web-service which are consumed ‘on-demand’ by the area of the solution which requests it (GESAWE)

Where possible, each 4GL, sub-program and web-service all have the same name for ease of debugging and are prefixed with XV1, followed by the object, followed by the action it is performing.

Commits

EDD or EDM do not make any commits to Sage, whereas the PIA solution does by adding Invoices to the PIH and BIS objects left list.

It does this by using the entry point standard script AWEB linked to a specific 4GL script XV1SPEWS to manage the left list.

A special Entry Transaction is used called OCR, which is a minimized version of ‘Full Entry’ containing just the required fields for the creation of a document minimizing the chance of issues.

Classic SOAP pool alias

This is the ‘gateway’ to allow connectivity to Sage X3 from an external source such as the EDM / PIA solutions. It requires the Endpoint, number of Hosts (connections), a language, and X3 user who has to have web-services connection ticked.

One classic pool alias is required per Sage Endpoint that wants to use EDM / PIA.

These follow a naming convention:

X3EDMENDPOINT

The text in red is the internal name of the endpoint to be used in conjunction with the solution, ie. X3EDMSEED, X3EDMPROD and so on. You setup these as part of the installation and it is covered in full in the documentation.

Lookup Definitions

The following table defines examples of how each lookup web-service for the appropriate area of the solution is labelled.

Where possible, they following a basic naming convention:

Start XV1
OBJECT
ACTION

LU = Lookup
LIST = Returning an array of values
CHK = Checking a value is valid

4GL	Sub-Program	Web-Service	Data In	Data Out
XV1SOHLU	XV1SOHLU	XV1SOHLU	CODE	ITRANS_COMP=[SOH]CPY ITRANS_SITE=[SOH]SALFCY ITRANS_TYPE=[SOH]SOHTYP IBPC_CODE=[SOH]BPCORD IORD_DAT=[SOH]ORDDAT IORD_VALUE=[SOH]ORDATI
XV1EDMLIST	XV1EDMLIST	XV1EDMLIST	MAXNUM CRIT SEARCH	CODE

CODE
This is typically the transaction number of the object you are requesting, in the above example we pass in the Sales Order Number and listing them.

MAXNUM (int)
The maximum number of results a lookup can contain, the ceiling typically being 1000 results.

CRIT (int)
The criteria of the lookup if it requires refinement.

SEARCH (Char)
The data passed in that you want to search the results for based on the lookup

Commits

Whereas EDM is exclusively Sub-program lookup based, PIA uses lookups and commits.

A commit uses the Sage X3 object as its basis for structure, so does not use / require a subprogram.

4GL	Sub-Program	Web-Service	Data In	Data Out
WJXV1OCRPIH	N/A	XV1OCRPIH	XV1OCRPIH.soap	stdout
WJXV1OCRBIS	N/A	XV1OCRBIS	XV1OCRBIS.soap	stdout

The 4GL is generated automatically by Sage X3 when published as part of the installation process.

The Web-services are provided by the PIA patches.

The data in is the soap file containing the commit definition is created 'on the fly' by:

PIA with DbCapture the C:\V1\DbCapture\defs\PIAExpress_EXPORT.def.
The Data out contains the response from Sage including a status for success / failure and where successful, the PIH / BIS Invoice number it has created.

Payloads

A payload is the file(s) created to facilitate to connection to Sage X3 and the exchange of data between Sage X3 and EDM / PIA.

EDM

Payloads are created when requesting data, triggering the associated web-service depending on what has been requested.

The following actions trigger a payload and their associated files, they are all created in the \V1Home\temp directory on the V1 Server.

NOTE: This area is periodically cleaned out automatically once an hour to preserve disk-space as once used, they are no longer required.

• Clicking the lookup/validate button in SmartDeposit
• Scanning a barcode in DbScanner
• Clicking the [EDM] Archive Transaction / Attachment button within Sage X3
• Where EDM has been purchased, distributing a document via EDD using the following destinations:
      • AUTO
      • EMAIL
      • FAX
      • PRINT

3 files are created per lookup, for example:

XV1FCYLIST.bat
XV1FCYLIST.soap
XV1FCYLISTRESPONSE.xml

The bat file contains the path to V1’s proprietary binary to perform http lookups and sets environment variables needed by the bat file:

@echo off
setlocal
set FUNCTION=%1
set XMLOUT=%2
C:\V1Home\utils\httppost -O nocookies -O noredir -O noauth -x resultXml -X "%XMLOUT%" -vv -e5 -s C:\V1Home\SmartConnect\Documents\26\283\XV1FCYLIST.soap

The soap file contains the connection information and lookup definition:

The xml is the response back from the request for data.

Any lookup will have 3 files and be named in this way and are created ‘on the fly’ by the scripting file triggered to make the request for data.

The advantage of having these files / this structure means can then be tested independently of the solution should any troubleshooting be required.

PIA

Similarly to EDM, payloads are created when requesting data, triggering the associated web-service depending on what has been requested.

The following actions trigger a payload and their associated files, but with PIA, they are all created in the DOCID directory on the V1 Server.

A large amount of files are generated to process a document in PIA, so having all the files for that document in its own dir have obvious advantages.

• When a document first arrives in DbCapture
• Clicking the Check button in the DbCapture Client
• Putting a document on hold
• Deleting a document

The main difference between EDM and PIA is PIA will also create data rather than only requesting it.

Rather than an xml payload, the POST of data is embedded in a soap file:

Process Flow

Now you have a basic understanding of how, the following give examples of a typical process might flow from clicking a button, to triggering a lookup and returning a value.

User Activity for SmartDeposit

• User has a PDF of Purchase Invoice PINGB02314040012 and wish to archive it
• User logs in to the V1 SmartPortal and select SmartDeposit
• Where prompted, they upload the PDF
• Where prompted they select the [PIH] Purchase Invoices table
• Where Prompted the enter an Invoice number of PINGB02314040012 and click the Lookup/validate button
• The web-service XV1PIHLU is triggered, passing the CODE (in this case PINGB02314040012) which returns the rest of the details in the xml response.
• This response is read, parsed and returned to the tags on screen ready to be archived.

User Activity for DbScanner

• User has a paper copy of Purchase Invoice PINGB02314040012 and wish to archive it
• User navigates to the Purchase Invoice in Sage X3, clicks the [EDM] Print Barcode link
• Barcode prints, this contains the Purchase Invoice number
• User attaches Barcode and logs in to DbScanner
• Where prompted, they scan the document
• The web-service XV1PIHLU is triggered, passing the CODE (in this case PINGB02314040012) which returns the rest of the details in the xml response.
• This response is read, parsed and returned to the tags on screen ready to be archived.

NOTE: The same script is triggered whether using SmartDeposit or DbScanner per document type, detail in the following chapter.

Server Activity

Soap file XV1PIHLU.soap is generated by V1X3_XV1PIH.def:

Bat file is generated generated by V1X3_XV1PIH.def:

@echo off
setlocal
set FUNCTION=%1
set XMLOUT=%2
C:\V1Home\utils\httppost -O nocookies -O noredir -O noauth -x resultXml -X "%XMLOUT%" -vv -e5 -s C:\V1Home\temp\XV1PIHLU.soap

Bat file is triggered, creating XV1PIHLURESPONSE.xml which is read, parsed for results which are returned to the interface that made the request.

Web-Service Structure

The following pages list of all the web-services and their role for EDM and PIA.

In each case the 4GL, Sub-Program and Web-Service are all the same name.

• To access any 4GL, in Sage, go to Development > Script Dictionary > Scripts > Script Editor (ADOTRT) and open the file
• To access any Sub-Program, in Sage, go to Development > Script Dictionary > Scripts > Subprograms (GESASU)
• To access any Web-Service, in Sage, go to Development > Script Dictionary > Scripts > Webservices (GESAWE)

For EDM, all lookups have a corresponding DbForm def file also of the same name.

These are all in the C:\V1\DbArchive directory.

So a web-service called XV1PIHLU is used by a def file called V1X3_V1PIH.def

For PIA, all lookups are named as closely as possible to the function they are performing.

EDM