Friday, July 14, 2017

Microsoft Dexterity: Customizing Safe Pay file name

Hello all!

It's been a while since I've worked on my blog as there's quite a bit going on these days: numerous projects at Mekorma, preparing to move to my new place, upcoming trips to Colombia and Fargo, ND, etc., so not much time to dedicate to writing.

Anyways, today I wanted to dive into some development. It is very often that I see on forums a request to be able to customize the Safe Pay file name and I wanted to address this with some Dexterity code, but first - you guessed it! - some background.


Safe Pay is part of Microsoft Dynamics GP's Electronic Banking suite of modules, comprised by Electronic Reconcile, EFT Payables and Receivables, and, well, Safe Pay. The goal of Safe Pay is to allow you to create a file that is sent to your bank to confirm the authenticity of checks and EFTs issued to payees.

Trivia: Who was the original author of the Electronic Banking suite?

The Safe Pay Configurator provides an intuitive (in most cases) user interface that allows you to define the specific file format(s) accepted by your bank(s).

Safe Pay Configurator window
Upon configuring the file format, you will then use the Safe Pay Bank Link Maintenance window to group all the checkbooks associated to the same bank into an Upload ID. As part of this setup, you can define a single file name to be generated for this bank. Naturally, most setups will include some company identifier (in a multi-company environment) and the checkbook to at least make the file unique and distinguishable enough.

Safe Pay Bank Link Maintenance window

Finally, the Safe Pay file itself can be generated only after the payment batch has been posted. For this, you must use the Safe Pay - Transaction Upload window. In this window, you will choose the Bank Upload ID defined above, and a cutoff date. Safe Pay will recall the (posted) payment transactions within the last upload date and the cutoff date entered by you. All checks and EFTs available for processing within that date range will show up for processing.

Safe Pay - Transaction Upload window

The Problem and The Solution

Most organizations would like to have at least a date stamp included as part of the file name itself. For the above example, our desired file name would be something like MMM29-FIRSTBANK-YYYYMMDD.txt, where YYYYMMDD represents the current year, month, and date. As you can tell from the Safe Pay Bank Link Maintenance window, it is not possible to achieve this. There isn't even an option to allow you to select other descriptors for the file name. In order to do this, we will use some Dexterity sanScript to add this feature.

NOTE: This article assumes you have a basic understanding of the principles of integrating Microsoft Dynamics GP applications and that you are familiar with the build process (extract and auto-chunk) of a development dictionary. If you need help setting up your development environment, take a look at the #Dexterity Development Environments series on the Winthrop Development Consultants blog by my good friend and fellow MVP, David Musgrave.

In order to change the Safe Pay file name, we will begin by setting a cross-dictionary trigger against the ME_Configurator_Write_Entire_Format global procedure in the Safe Pay dictionary in our Startup script. You can find this out by capturing a script log by using the Microsoft Dynamics GP Script Debugger tool or taking advantage of the GP Power Tools manual or automatic logging capabilities.

global procedure: Startup

{ Script: Startup
  Created by Mariano Gomez, MVP
  This code is licensed under the Creative Commons 
  Attribution-NonCommercial-ShareAlike 4.0 International (CC BY-NC-SA 4.0) license.

local integer lresult;

pragma(disable warning LiteralStringUsed);
lresult = Trigger_RegisterProcedureByName(1235, "ME_Configurator_Write_Entire_Format", TRIGGER_AFTER_ORIGINAL, script Change_Safepay_File_Name);

if (lresult <> SY_NOERR) then
 warning "Trigger registration error for procedure ME_Configurator_Write_Entire_Format in dictionary SafePay (1235): script Change_Safepay_File_Name";
end if; 

pragma(enable warning LiteralStringUsed);

When ME_Configurator_Write_Entire_Format procedure executes, our script processing procedure, Change_Safepay_File_Name, will fire in response, after the original Safe Pay script is executed. This script makes extensive use of standard Microsoft Dynamics GP global functions, which demonstrates how your integrating code can become really compact if you do some upfront work to understand what's available to you in the core Dynamics.dic dictionary file.

global procedure: Change_Safepay_File_Name

{ Script: Change_Safepay_File_Name
Created by Mariano Gomez, MVP This code is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International (CC BY-NC-SA 4.0) license. }
in string FormatId;
in string SafepayId;
in string UploadId;
in string FilePathName;
out boolean WroteAll;

local boolean  fExists;
local string  sPath, sFileName, sGeneric;
local string  sTimeStamp;
local integer  nStatus;

sGeneric = Path_MakeGeneric(FilePathName);

{ @@@. Verify the generated SafePay file exists and can be open. }
fExists = File_Probe(sGeneric);

if (fExists) then
 sPath = Path_ParsePathFromPath(FilePathName);
 sFileName = Path_ParseFileFromPath(FilePathName);

 { @@@. Get the current time stamp as a string in YYYYMMDD format. We retrieve the time from the SQL Server. 
   We also take advantage of the RW_Pad Report Write function to add the leading zero to single digit months and days
 sTimeStamp = str(year(sysdate(CURRENT_SERVER))) 
   + RW_Pad(str(month(sysdate(CURRENT_SERVER))), LEADING, ZERO_STR, 2) 
   + RW_Pad(str(day(sysdate(CURRENT_SERVER))), LEADING, ZERO_STR, 2);
 { @@@. Call the Microsoft Dynamics GP global function FileName_AppendToName to append the string time stamp }
 sFileName = FileName_AppendToName(sFileName, CH_UNDERSCORE + sTimeStamp);
 { @@@. Call the Microsoft Dynamics GP global function File_Rename to rename the Safe Pay file with the new name }
 nStatus = File_Rename(FilePathName, sPath + sFileName, true); 
end if;

Note that our script processing procedure uses the same parameter list as the ME_Configurator_Write_Entire_Format Safe Pay procedure. This allows us access to the file path and name as configured in Safe Pay.

You can download the extracted dictionary and chunk file here. Feel free to customize the code as you see fit.

Until next post!

Mariano Gomez, MVP

No comments: