Data & Automation API: DmzUploadFile

DmzUploadFile

Use this job type to upload a file stored in one of your DMZ folders to an external site via SFTP. The file can also be renamed during the upload.

But… consider using our newer DmzUploadSpool method to transfer files to external sites via SFTP. DmzUploadSpool allows you to transfer all the files stored in your folder in one move and all the files are archived automatically. This makes file naming and management much simpler.

dmzUploadFile is sometimes used in conjunction with a dmzMoveFile job to make sure the file has been created fully before it's made available for SFTP polling by an external system. Use the following steps:

1. Create an interfaceQuery job to build the file using a temporary filename, or place the correctly named file into a temporary sub-folder
2. Create a dmzMoveFile child job to rename the file and/or to place the file into the folder that will be polled by the external system
3. Create a dmzUploadFile child job to upload the file to the external SFTP location (if required)

Parameters

The Scheduler / Job tab displays the following parameters when this method has been selected.

• Dmz filename — Enter the file path and name of the file the DMZ area that will be copied and uploaded to the SFTP destination. E.g. /supplierabc/out/report.csv
• Destination — Drop down list which shows the stored active sftp connections added in gbdmzuploadfiledestinations table. Destination filename Is the absolute path within the destination sftp system where the file will be uploaded. Destination filename can include the system date and time by using the syntax based on the following link strftime — format a local time/date according to locale settings,please refer. some examples below:- *If I give %y%m%/d it should reflect todays date. E.g. 20180530 *If I give %d/%m%Y it should reflect todays date. E.g. 30/05/2018 *If I give %A it should reflect the day of the week. E.g Wednesday *If I give %c it should reflect todays date and time. E.g. Wed May 30 00:45:10 2018

Set-up

For a dmzUploadFile job to work, the SFTP access credentials need to be stored in the table gbdmzuploadfiledestinations.

Contact Catch-e Support when you need to get a new record added to this table.

Outbound files can be encrypted on transfer if the SFTP credentials are stored with an encryption key.

The encryption key is coded into base64 on deployment, so it must be decoded if checks are required.

The supported encryption method is GPG (which is the open-source implementation of PGP).

The format used for digital transmission is ASCII. This means encrypted files will have an .asc extension.

Outgoing encryption key_name

If you are using a set-up that encrypts outgoing files, the encryption key_name needs to contain the email address that is linked to the encryption key.
Set-up the record with just the email address first. E.g. keyprovider@encrypt.com.au
If these files do not transfer, confirm the name attached to the email address and try adding that. E.g. Encrypt Businesskeyprovider@encrypt.com.au

Warning: An incorrect setting here is the most common cause of failure in this area. Investigate this setting first.

IP Addresses

The receiving organisation may want the following IP addresses so they can configure them as allowable senders.

CATCHEERRORDMZDESTINATIONNOTFOUND

• CATCHEERRORDMZFILENAMENOTFOUND — This error will show if 1. The specified file does not exist 2. Your encryption keyname is not correct. CATCHEERRORDMZSFTPPUT_FAILED An SFTP connection could not be established to transfer the file. 1. The credentials may not be valid. "system::dmzuploadfile DMZ SFTP PUT failed. Error code: 67." Indicates invalid or expired SFTP credentials. 2. The DMZ folder may not be available. "system::dmzuploadfile DMZ SFTP PUT failed. Error code: 79." Indicates an SSH connection issue or insufficient space on the target device.

DmzUploadSpool

Use this job type to transfer all the files stored in one of your DMZ folders to another site via SFTP. The transferred files are also archived.

dmzUploadSpool can be used in conjuction with other jobs to create, then transfer files for your business processes.

dmzUploadSpool can be scheduled to run as a child job, or it can run separately on its own schedule.

• Use gl / jde / createExportBatch) to create accounting files. Then use dmzUploadSpool to transfer the files to your accounting system.
• Use gl / greentree / createExportBatch) to create accounting files. Then use dmzUploadSpool to transfer the files to your accounting system.
• Use gb / queries / interfaceQuery to create custom reports. Then use dmzUploadSpool to transfer the files to a business supplier.

Parameters

The following parameters are displayed when this method has been selected.

CATCHEERRORDMZDESTINATIONNOTFOUND

• CATCHEERRORDMZSFTPPUTFAILED — An SFTP connection could not be established to transfer the file. Check with the organisation that manages the destination SFTP server. It may be undergoing maintenance or have had a short-term outage when the job was run.

Set-up

For a dmzUploadSpool job to work, the SFTP access credentials need to be stored in the table gbdmzuploadfiledestinations.

Contact Catch-e Support when you need to get a new record added to this table.

IP Addresses

The receiving organisation may want the following IP addresses so they can configure them as allowable senders.

Dmz Move File

This allows you to move a file from one DMZ folder to another, or simply to rename a file in preparation for an SFTP transfer.

dmzMoveFile is sometimes used in conjunction with a dmzUploadFile job to make sure the file has been created fully before it's made available for SFTP polling by an external system. Use the following steps:

1. Create an interfaceQuery job to build the file using a temporary filename, or place the correctly named file into a temporary sub-folder
2. Create a dmzMoveFile child job to rename the file and/or to place the file into the folder that will be polled by the external system
3. Create a dmzUploadFile child job to upload the file to the external SFTP location (if required)

But… you may not need a job like this if you use DmzUploadSpool jobs to transfer files to external sites via SFTP. DmzUploadSpool allows you to transfer all the files stored in your folder in one move and all the files are archived automatically. This makes file re-naming unnecessary and management much simpler.

Parameters

The Scheduler / Job tab displays the following parameters when this method has been selected.

BillingReprintWebService

This API replicates the system's Billing / Re-print function.

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

Enable

Go to Setup / Reference Data → gbcontrols) and find the "apiwebserviceswrapper_login" control.

Populate this control with a 'web_services' user login and password.
This user will be used to run the API from within code.

Permissions

To run this API, the nominated 'web-services' role needs to be given permission.

If you are not actively using the API, leave the permission off for better security.

Go to Roles / Apis and check on WebServices.

Authentication

Authenticate with the API before running this API.

HTTP Method

Use the HTTP Method 'POST' for consuming this web service.

URL Examples

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

Headers

Body (form-data)

Response Details

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

| The request was successful request. For Postman users: Use the "Save Response" option to download the PDF file to your chosen file location to view. |
| 401 - Unauthorized | | |

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

| You have not authenticated before running this API or The token_timeout of the current session has passed. You need to authenticate again. |
| 403 - Forbidden | | |

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

| You do not have permissions for this request. Go to System Roles and enter 'web_services' Navigate to the Roles / APIs tab to make sure the permission you need to run this API is checked. |
| 406 - Not Acceptable | | |

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

| The Accept Header must be set as 'application/octet-stream'. Update the Accept Header and try again. |
| 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"}

| You need to enable Web Services Go to Setup / Reference Data → gbcontrols) and find the "apiwebserviceswrapperlogin" control. Populate this control with a 'webservices' user login and password. This user will be used to run the API from within code. |
| 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"}

| Input field invoice_no is not a valid Invoice No. Invoices at 'deleted' status cannot be re-printed. |
| 424 - Failed Dependency | | |

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

| The API cannot run at this time. This can happen for a various reasons, for example: service resource limits have been exceeded the system is in maintenance mode |

ImportTransactions

This job will import and post card service files (e.g. fuel transactions) by automating the steps defined in Card Transactions.
It targets import file(s) stored in your DMZ area.
Each file is removed once it has been processed.

Related page: WEX Motorpass

Parameters

• Card Interface — Is the interfacecode from fminterfaces for the card supplier providing the files. A search icon is provided to find search for this. Card Interface cannot be blank.
• File Pattern — A regular expression pattern used to match the card file(s) within the DMZ Subfolder. e.g. ^FMFP[0-9]{4}.txt$ will match FMFP0122.txt, FMFP0123.txt… File Pattern cannot be blank.
• DMZ Subfolder — Is the subfolder in the DMZ area where the card file(s) are to be found. If left blank, the DMZ home folder will be used. Subfolders can be nested. Example : 'fuel/out'

Queue

• Recycling (Check Box) — Check to recycle the job when it completes successfully. We recommend this field be checked for this type of job.

Import Process Outcomes

When the Scheduler job is triggered, one of the following outcomes will occur.

If ) is set to 'yes', card transactions will be processed and imported even when the card's "Status" is 'inactive'. The default setting is "no".