DmzUploadFile

Upload file stored in DMZ folder to external site via SFTP. File can be renamed during upload.

Note: Consider using newer DmzUploadSpool method to transfer files via SFTP. DmzUploadSpool transfers all files in folder in one move with automatic archiving, simplifying file naming and management.

dmzUploadFile sometimes used with dmzMoveFile job to ensure file created fully before SFTP polling by external system.

Workflow Steps

Create interfaceQuery job to build file using temporary filename, or place correctly named file into temporary sub-folder
Create dmzMoveFile child job to rename file and/or place into folder for SFTP polling
Create dmzUploadFile child job to upload file to external SFTP location (if required)

Parameters

Parameter	Notes
DMZ Filename	File path and name in DMZ area to copy and upload. Example: /supplierabc/out/report.csv
Destination	Drop-down list of stored active SFTP connections from gbdmzuploadfiledestinations table
Destination Filename	Absolute path within destination SFTP system. Can include system date/time using strftime syntax. Examples: %y%m%d = 20180530, %d/%m/%Y = 30/05/2018, %A = Wednesday, %c = Wed May 30 00:45:10 2018

Setup

SFTP access credentials stored in gbdmzuploadfiledestinations table. Contact Catch-e Support to add new records.

Outbound files can be encrypted on transfer if SFTP credentials stored with encryption key. Encryption key coded into base64 on deployment (must be decoded for checks). Supported encryption: GPG. Digital transmission format: ASCII (.asc extension).

Encryption Key Setup

If using encryption, key_name must contain email address linked to encryption key.

Set record with email address first. Example: keyprovider@encrypt.com.au

If files don't transfer, confirm name attached to email address and try adding it. Example: Encrypt Business keyprovider@encrypt.com.au

Warning: Incorrect encryption key_name is most common cause of failure. Investigate first.

gbdmzuploadfiledestinations Table Schema

Field	Datatype
dmzuploadfiledestinationid	int(10) unsigned
name	varchar(50) NOT NULL
type	ENUM (sftp) NOT NULL
configuration	BLOB [encrypted]
Host	sftp.supplier.com
Port	22
Username	Name
Password	Password
Key	Password
Encryption - key_name	keyprovider@encrypt.com.au
Encryption - key	encryption key (base64 coded)
status_flag	enum('active','inactive')

IP Addresses

Receiving organisation may need these IP addresses for firewall configuration:

Environment	Location	IP Addresses
Live	gw.aws.catch-e.com.au	52.64.49.97 or 52.64.24.222
Staging	gw.example.catch-e.com	xx.xx.xx.xx or xx.xx.xx.xx

Error Codes

CATCH_E_ERROR_DMZ_DESTINATION_NOT_FOUND

CATCH_E_ERROR_DMZ_FILENAME_NOT_FOUND - Shows if:

Specified file does not exist
Encryption keyname incorrect

CATCH_E_ERROR_DMZ_SFTP_PUT_FAILED - SFTP connection could not be established:

Invalid credentials: "system::dmzuploadfile DMZ SFTP PUT failed. Error code: 67"
DMZ folder unavailable: "system::dmzuploadfile DMZ SFTP PUT failed. Error code: 79" (SSH connection issue or insufficient space)

DmzUploadSpool

Transfer all files stored in DMZ folder to another site via SFTP. Transferred files automatically archived.

Can be used with other jobs to create then transfer files. Can be scheduled as child job or separately.

Use Cases

Use gl / jde / createExportBatch to create accounting files, then dmzUploadSpool to transfer to accounting system
Use gl / greentree / createExportBatch to create accounting files, then dmzUploadSpool to transfer
Use gb / queries / interfaceQuery to create custom reports, then dmzUploadSpool to transfer to business supplier

Parameters

Parameter	Type	Notes
DMZ In Subfolder	Text	File path in DMZ area for files to transfer. Example: jde/in
Destination	List	Stored active SFTP connections available. Stored in gbdmzuploadfiledestinations table.
Destination Folder	Text	Absolute path within destination SFTP system for upload
DMZ Out Subfolder	Text	Folder path in DMZ to store copies of transferred files for organization

Setup

SFTP access credentials stored in gbdmzuploadfiledestinations table. Contact Catch-e Support for new records.

gbdmzuploadfiledestinations Table Schema

Field	Datatype
dmzuploadfiledestinationid	int(10) unsigned
name	varchar(50) NOT NULL
type	ENUM (sftp) NOT NULL
configuration	BLOB [encrypted]
Host	sftp.supplier.com
Port	22
Username	Name
Password	Password
Key	Password
Encryption - key_name	keyprovider@encrypt.com.au
Encryption - key	encryption key (base64 coded)
status_flag	enum('active','inactive')

IP Addresses

Receiving organisation may need these IP addresses for firewall configuration:

Environment	Location	IP Addresses
Live	gw.aws.catch-e.com.au	52.64.49.97 or 52.64.24.222
Staging	gw.example.catch-e.com	xx.xx.xx.xx or xx.xx.xx.xx

Error Codes

CATCH_E_ERROR_DMZ_DESTINATION_NOT_FOUND

CATCH_E_ERROR_DMZ_SFTP_PUT_FAILED - SFTP connection could not be established. Check with destination SFTP server organization. May be undergoing maintenance or short-term outage when job ran.

DmzMoveFile

Move file from one DMZ folder to another or simply rename file in preparation for SFTP transfer.

Sometimes used with dmzUploadFile job to ensure file created fully before SFTP polling by external system.

Note: May not need this job if using DmzUploadSpool to transfer files via SFTP. DmzUploadSpool transfers all files in folder in one move with automatic archiving, making renaming unnecessary and management simpler.

Workflow Steps

Create interfaceQuery job to build file using temporary filename, or place correctly named file into temporary sub-folder
Create dmzMoveFile child job to rename file and/or place into folder for SFTP polling
Create dmzUploadFile child job to upload file to external SFTP location (if required)

Parameters

Parameter	Notes
From Filename	Name within DMZ area to move or rename. Sub folders can be included. Example: /export/out/target_file
To Filename	New file name. Sub folders can be included and will be created if don't exist

BillingReprintWebService

Replicates system's Billing / Re-print function.

Supplementary SWAGGER documentation: api.catch-e.com/docs/#/Web%20Services/billingReprintWebService

Setup

Go to Setup / Reference Data and find gbcontrols "apiwebserviceswrapper_login" control. Populate with 'web_services' user login and password for API use.

Permissions

To run this API, nominated 'web-services' role needs permission.

If not actively using, leave off for better security.

Go to Roles / APIs and check on WebServices.

Authentication

Authenticate with the API before running this API.

HTTP Method

POST

URL Examples

https://api.catch-e.com/web-services/fm/billing/reprint

Headers

Key	Value	Notes	Mandatory
Accept	application/octet-stream	Required setting	Yes

Body (form-data)

Key	Value	Notes	Mandatory
invoice_no	string	Invoice No	Yes

Response - 201 Created

%PDF-1.3 3 0 obj<</Filter /FlateDecode /Length 1983>>stream

Successful request returns PDF file. For Postman users: Use "Save Response" option to download PDF to chosen location.

Response - 401 Unauthorized

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Unauthorized", "status": 401, "detail": "Unauthorized" }

You have not authenticated or token_timeout has passed. Authenticate again.

Response - 403 Forbidden

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Forbidden", "status": 403, "detail": "Forbidden" }

You do not have permissions. Go to System Roles, enter 'web_services', navigate to Roles / APIs and check permissions.

Response - 406 Not Acceptable

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Not Acceptable", "status": 406, "detail": "Cannot honor Accept type specified" }

Accept Header must be 'application/octet-stream'. Update and try again.

Response - 418 Invalid Credentials

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Invalid Credentials", "status": 418, "detail": "Web services API wrapper credentials have not been configured" }

Enable Web Services. Go to Setup / Reference Data and find apiwebserviceswrapper_login control. Populate with 'web_services' user login and password.

Response - 422 Unprocessable Entity

{ "validation_messages": { "invoice_no": { "invoiceNotFound": "Invoice No '1999999' not found" } }, "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Unprocessable Entity", "status": 422, "detail": "Failed Validation" }

invoice_no not valid. Invoices at 'deleted' status cannot be re-printed.

Response - 424 Failed Dependency

{ "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html", "title": "Failed Dependency", "status": 424, "detail": "Upstream service temporarily unavailable. Please retry." }

API cannot run at this time. Service resource limits exceeded or system in maintenance mode.

ImportTransactions

Import and post card service files (e.g. fuel transactions) by automating Card Transactions steps. Targets import files in DMZ area. Each file removed once processed.

Related: WEX Motorpass

Parameters

Parameter	Notes
Card Interface	Interface code from fminterfaces for card supplier providing files. Search icon provided. Cannot be blank.
File Pattern	Regular expression pattern to match card file(s) in DMZ Subfolder. Example: ^FMFP[0-9]{4}.txt$ matches FMFP0122.txt, FMFP0123.txt. Cannot be blank.
DMZ Subfolder	Subfolder in DMZ area for card file(s). If blank, DMZ home folder used. Subfolders can be nested. Example: 'fuel/out'

Queue

Parameter	Notes
Recycling (Checkbox)	Check to recycle job when completes successfully. Recommended for this job type.

Import Process Outcomes

Result	Cause	Comments / Action
Failed Import	File does not import - Incorrect file format	Confirm file received is in expected format/content. Contact fuel supplier representative if needed.
Failed Import	File does not import - Duplicate File	File previously imported
Failed Import	File does not import - .zip file	Scheduled process does not accept .zip files
Import with Validation Warnings	Pending status - Incorrect product	Batch created, retrievable from Card Transactions screen. Follow resolution process.
Import with Validation Warnings	Pending status - Incorrect gl code	Batch created, retrievable from Card Transactions screen. Follow resolution process.
Import with Validation Warnings	Pending status - Failed card	Batch created, retrievable from Card Transactions screen. Follow resolution process.
Import with Validation Warnings	Pending status - Failed date	Batch created, retrievable from Card Transactions screen. Follow resolution process.
Import with Validation Warnings	Posted status - Expired Card	Batch created, retrievable from Card Transactions screen. Follow resolution process.
Import with Validation Warnings	Posted status - Duplicate transaction	Batch created, retrievable from Card Transactions screen. Follow resolution process.
Successful Import	Posted status	Batch created, retrievable from Card Transactions screen

Inactive Card Handling

If fminterfaces.process_inactive_card_flag set to 'yes', card transactions processed and imported even when card 'Status' is 'inactive'. Default: 'no'.