It is simple to call a stored procedure through a RESTful API call if you have Catalina’s API for Dynamics SL. You can call any stored procedure and pass parameters and retrieve data.
This is a demo on how to call a stored procedure using Postman and Catalina’s API for Dynamics SL.
First, to do this demo, you need to download and install Postman. Postman is a developer tool that allows you to interact with API’s easily so that you can test API calls to see how you call them and what data is returned. You can get Postman here: https://www.postman.com/
In the demo, we are going to call the stored procedure SOHeader_all. This stored procedure retrieves all Sales Order Headers (SOHeader) for a particular CpnyID and OrdNbr. NOTE: this is just an example. With Catalina’s API, you can call any stored procedure.
SOHeader_all has 2 parameters: – @parm1: This parameter is for the CpnyID – @parm2: This parameter is for the OrdNbr (can use a wildcard like ‘O000%’ which will bring back all orders that start with O000.
You can see what the procedure looks like here:
@parm1 varchar( 10 ),
@parm2 varchar( 15 )
WHERE CpnyID = @parm1
AND OrdNbr LIKE @parm2
ORDER BY CpnyID,
So, if you wanted to retrieve all orders that started with “O000” for CpnyID = “0060” you would call the stored procedure like this:
exec SOHeader_all @parm1='0060', @parm2='O000%'
So, now how to call this using Postman through Catalina’s API for SL?
First you need to know where your Catalina API is installed. I am going to use the server name yourserver.com as the domain name. So, for this example, we would look at the endpoint as the following:
As you can see above, you would replace yourServer.com with wherever your server is. And you can see <ProcedureName> in the URL. this would be replaced with the actual stored procedure name you want to call (in this example, we are going to replace it with SOHeader_all). So, the new URL for the endpoint would look like the following:
In Postman, you would make it look like below. NOTE: when calling a customSQL stored procedure, you must use the action type of “POST”
Next, you need to set the authentication. This is done on the “Authorization” tab. Catalina’s API uses “Basic Auth”. So, make sure that you set the type for “Basic Auth” in the dropdown. And then enter the username and password that was given to you from your installer.
After that, you will have been given a SiteID from your installer. You will need to create a Header for that SiteID. You do this on the headers tab. You should enter that SiteID (in my example it is “DEFAULT”, but you would use the SiteID given to you by your installer) and the default CpnyID (in my example that is “0060”, but you would use your CpnyID of your database)
Finally, you will want to enter the body of the parameters that are being passed. There are 2 parameters for SOHeader_all (@parm1 and @parm2). The format of the body that you would set is below.
This is a demo that shows you how to create a mobile app to interact with Dynamics SL to provide a “Contact Free” payment solution to help protect your employees and customers during COVID 19. The intended user of this example app would be a customer service rep, sales person, or field service rep who needs to collect payment from a customer (handy for collecting a deposit or down payment before delivery, installation, or service work to be done).
This demo uses Catalina’s API to search customers in SL and then lets the user to request a payment from a customer by generating a link and emailing it to the chosen customer. That customer then can click on the link and pay the amount which automatically creates a payment in SL’s AR.
Check out the video of the demo on our Youtube channel here:
Below is a screenshot of the Android app from the above demo. First you can search for a customer by a keyword. That search will then bring back a list of results. You can then click on the customer you want to request funds for. The app will automatically fill in the email address of the customer (from the Customer record in Dynamics SL). You can change the email address if you want. You then enter a requested payment amount and hit submit. Once you do this, Catalina’s SLQuickPay will send off an email to the customer with a link which will then allow them to make a PCI compliant secure payment. Once authorization occurs, SLQuickPay will then create a payment in Dynamics SL automatically.
As mentioned below, if you want to have starter code on creating an Android App (with Visual Studio and Xamarin), you can check out an example on our Github here (NOTE: I would only consider this a starter. This is in no means something finished but enough to get you started)
Getting paid by your customers can sometimes be difficult. Catalina’s payment portal allows users to login and manage their account and pay their invoices. But customers still need to login.
To reduce the barrier of entry for customers to pay, Catalina has come up with SLQuickPay. SLQuickPay allows you to send out a link via email or SMS which the customer clicks on. They are then sent to a payment page without any login required. They simply pay (Credit Card or ACH). Once that payment is authorized and captured, SLQuickPay creates the payment in Dynamics SL.
The above shows how you can request for an amount not tied to any invoice. This is especially handy if you need to capture a deposit against a sales order, service call, etc. This payment would go into the SL “Payment Entry” screen.
The demo shows how you can request a payment from the sales order screen for a deposit amount. This would then send a link to the user via email. The user would click on the link and pay.
The request payment allows you to decide an amount to charge for a deposit for the order. It also has a handy percentage calculator to take out the guess work.
NOTE: SLQuickPay also has the ability to send out a simple link to pay for an invoice and have that payment applied to one or more invoices through the “Payment Application Screen”
Catalina’s SLQuickPay is a way to send a request for payment to your customer as an email with a link to click to pay. Your customer simply clicks on it and pays (no need for a portal login or anything). The payment works through a PCI compliant payment processor and is automatically integrated back into Dynamic SL’s AR.
There are many ways to create SLQuickPay links. One of which is calling a stored procedure by passing a few parameters.
The stored procedure is called: xct_spSLPaddInvoicePaymentRequest
The parameters to this proc is:
@batNbr: The batch number of the invoice you want to send
@refNbr: The invoice number you want to send
@CustID: The customer who the link is going to be going to
@paymentEmailList: A delimited list of email addresses the link will be sent to
@siteID: (optional) For which configuration site to use (defaults to ‘SLPAY’)
@setupID: (optional) The PayFabric setupID you are to send. If not passed, the default will be used from SLQuickPay’s configuration
@deviceID: (optional) The PayFabric deviceID you are to send. If not passed, the default will be used from SLQuickPay’s configuration
You can call this stored procedure from most anything. You could call it from a trigger when an invoice is created. You can call it from a SL screen. Or even another application all together (like maybe excel that has a list of invoices to send)
Here is an example of how I added a button on the Invoice and Memo screen to send a SLQuickPay Link for a particular invoice.
Below, you can see where I created a button “Send SLQuickLink” that will take the current invoice on the screen and send a payment request link to the customer.
Below is the code behind the click event of the button. This will look at the current batNbr, refNbr (invoice number), custID, and get the email tied to the customer to send the link to that customer’s email.
Private Sub bPayLink_Click()
Dim SQLStr As String
Dim Csr_temp As Integer
Dim sCustID As String
Dim recfound As Integer
Dim maintflg As Integer
sCustID = GetObjectValue("ccustid")
SQLStr = "Customer_All " + SParm(sCustID)
serr = SqlFetch1(Csr_temp, SQLStr, bCustomer, LenB(bCustomer))
Dim lsSQL As String
Dim liCursor As Integer
lsSQL = "xct_spSLPaddInvoicePaymentRequest" & SParm(ThisScreen.cbatnbr.Text) & SParm(ThisScreen.crefnbr.Text) & SParm(ThisScreen.ccustid.Text) & SParm(bCustomer.EMailAddr) & SParm("SLPAY")
Call sql(liCursor, lsSQL)
MsgBox ("SLQuickLink Sent to CustID " + ThisScreen.ccustid.Text + " for invoice " + ThisScreen.crefnbr.Text)
If you need EDI integration between your trading partners and Dynamics SL, you can use Catalina’s API for SL to get data in and out of Dynamics SL. One of the simplest of transactions is order management. If you have a trading partner that needs to send you PO’s so that you can then fulfill, the most common documents used are:
850: This is a purchase order to fulfill
855: An immediate response sent back to your trading partner acknowledging that you received the transaction
997: An acknowledgement that you have received the transaction and often when you will pass back a reference number for your internal order number
856: A shipper notification that notes what has shipped on the PO when a shipper is generated
The key to this is a data mapping layer that allows you to translate the inbound EDI documents and transform it into something that the Catalina API can understand. The reverse is true when data needs to be sent from SL out to your trading partner. The Catalina API will retrieve the data and then the translation will transform that data into an EDI document to send back to your customer.
Many of Catalina Technology’s stored procedures accept a field called @parms that is an XML field for configurable parameters to be passed. An example of this is below.
You can see that there is a parameter getting passed called “@parms”. In that is a XML string that contains one or more parameter. In this case, there is a single parameter called “ADDRID” and it is getting passed the value of “C%” so that it can return all addresses that start with a “C”
COVID-19 has made sending out invoices and getting paid has become a challenge. Catalina’s Account Central is a customer portal, for Dynamics SL, that allows customers to review statements, pay invoices or against their account, and manage their customer account in SL. All payments are through a PCI compliant payment processor. And all transactions are completely integrated with Dynamics SL
ctConfigEditor is the stand-alone executable used to create and edit the custom XML documents used to configure our full line of web services. Our xml structure supports storing sql connection data and a range of name/value pairs. All data is easily encryptable for added security.
Choose whether you are editing an existing file or creating a new config file from scratch. If loading an existing config file, you will need to fill in your catalina software license key as well as your sitekey.
Either load an existing Site ID or create a new Site ID. You can identify which Site ID you are editing on all screens at the top of the screen where it says, “Currently Editing: SiteID“. If this value is blank, it means you are creating a new SiteID entry. Note: TO DEFAULT ALL KEYS: Load an existing Site ID, then enter a New Site ID and hit the “Create Site” button.
Set your Database connection strings. Both the .NET format and OLE String format. .NET Format: user id=USERNAMEHERE;password=PASSWORDHERE;database=DATABASENAMEHERE;server=SERVERNAMEHERE OLE Format: Provider=SQLOLEDB;User Id=USERNAMEHERE;Password=PASSWORDHERE;Initial Catalog=DATABASENAMEHERE;Data Source=SERVERNAMEHERE For more information on sql connection strings and other options available, we recommend reading at: http://www.connectionstrings.com/
Edit the config options available or create custom entries. Note: you can optionally encrypt any field by just checking the “encrypt” checkbox next to a key. We recommend only encrypting sensitive data.
On the “Finish” tab you will see the option to Preview the XML file or Save it to a file. Click the appropriate button. You can optionally change your siteKey/encryptKey by filling in the new key in the SiteKey text field. Note: You will need to remember to update any client applications to use the new siteKey.
Catalina has had a way to call custom stored procedures from their SOAP based web services for Dynamics SL for years. You can now do it using the RESTful API version.
Looking at the Swagger Documentation, you can now see a customSQL resource (If you don’t see this, contact Catalina Support to see about getting updated to the latest version of Catalina API for Dynamics SL)
NOTE: the checksum is a security feature that is turned on by default. This allows the API to double check to make sure that you are who you say you are. Use a SHA1 hash of the stored procedure name to generate the checksum.
The checksum requirement can be disabled in your DSLCONFIGFILE.xml file.
You can generate the checksum using any SHA1 library, or you can use the library included in our service distribution: /ctDynamicsSL/bin/ctStandardLib.dll
var checksum = ctStandardLib.ctHelper.getHash(siteKey, storedProcedureName);