Catalina Integration Architecture

Typical Catalina Integration Architecture

Normally, Catalina will develop a Data Mapping App which will pull from one system, transform the data pulled, then push into the other system. This creates a situation where a hole is not needed to be opened in the firewall for outside systems to communicate in.

There are several ways that the Data Mapping App could communicate with the external SAAS system:

  • FTP: The app could send and receive data via an FTP, SFTP file share.
  • An API: The app could communicate via an API by posting and retrieving data through some type of web based API or Web Service
  • File Share: Some SAAS systems will communicate simply with files saved in a local fileshare.

The Data Mapping APP will communicate to Dynamics SL through Catalina’s API for SL (either via the SOAP based web services or the RESTful API. The Catalina API would reside inside the firewall on a Windows IIS server. The Catalina API will then communicate with the Dynamics SL database via a SQL Connection.


Call Stored Procedures Using Catalina’s API for Dynamics SL and Postman

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:

PROCEDURE [dbo].[SOHeader_all]
	@parm1 varchar( 10 ),
	@parm2 varchar( 15 )
AS
	SELECT *
	FROM SOHeader
	WHERE CpnyID = @parm1
	   AND OrdNbr LIKE @parm2
	ORDER BY CpnyID,
	   OrdNbr DESC

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:

http://yourserver.com/ctDynamicsSL/api/customSQL/<ProcedureName>

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:

http://yourserver.com/ctDynamicsSL/api/customSQL/SOHeader_all

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.

{
    "parameters": [
        {
            "name": "parm1",
            "value": "0060"
        },
        {
            "name": "parm2",
            "value": "O0005121"
        }
    ]
}

So, your Body tab in Postman would look like this (NOTE: make sure you select the “raw” radio button as shown below)

Then all you have to do is simply hit the “Send” button and the system should retrieve the results from your stored procedure call. In my example, it looks like below


Create a Contact Free Payment Solution for Dynamics SL (Mobile App)

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.

NOTE: Source code for the mobile app can be found on Github here: https://github.com/CatalinaTechnology/SL-Mobile/tree/main/ctPayment

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 SLQuickCollect 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, SLQuickCollect 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)

https://github.com/CatalinaTechnology/SL-Mobile/tree/main/ctPayment


Problem with Special Characters in Catalina API Query String

I ran into an issue earlier where I was trying to retrieve a customer using the Catalina Technology API for Dynamics SL. But the problem was that the CustID had special characters in it. In this case, the CustID looked like this: “BB& 1 2

So, there was a prefix of “BB”, then there was an ampersand, and then there were two spaces, then the number 1, two more spaces, then the number 2.

First of all, I had to URL encode the CustID that was getting passed to my API so that the call looked like this:

/api/financial/accountsReceivable/customer/BB%26%20%201%20%202

You can see that & was replaced by %26 and a space was replaced by %20.

Now, that is fine, but then .NET was having problems with the & (even encoded) in that it had an error like this:

A potentially dangerous Request.Path value was detected from the client (&amp;).

This is remedied by looking at the web.config of your ctDynamicsSL application. Search for the keyword: httpRuntime. Once you found that, if you don’t already have an attribute requestPathInvalidCharacters in that key, add it. This is a good default one:

<httpRuntime requestPathInvalidCharacters="&lt;,&gt;,%,&amp;,:,\,?" />

Then from that remove the &amp; so that you will allow the & to go in. That way, your final httpRuntime should look similar to this:

<httpRuntime requestPathInvalidCharacters="&lt;,&gt;,%,:,\,?" />

As you can see above, I removed &amp;, from the invalid characters. Thus allowing the ampersand to be allowed.

NOTE: If your httpRuntime has other attributes like the .NET version, etc. Leave those alone. Just worry about the requestPathInvalidCharacters attribute and it’s value.


3D Print a House Key from a Photo

This is a video I did back in 2017 where I took a photo of a house key and 3D printed it and it actually worked. NOTE: This key wasn’t the strongest of keys. And only worked a few times. But it is only needed once to make it a bad day for a home owner. Beware when you post pictures that include your keys in them.


Access Catalina’s API for Dynamics SL using .NET Core

If you are looking to build a cross platform application in .NET Core that can access Dynamics SL, you can use Catalina’s API for Dynamics SL. This is a demo on how you can do it using Visual Studio and deploy the client to Windows, Mac, and/or Linux (or any OS that supports .NET Core).

Demo on Connecting to Dynamics SL through .NET Core

You can get the source code for this demo on our GitHub site: https://github.com/CatalinaTechnology/dotNETCore/MyConsoleApp



URL’s for PayFabric and Catalina’s Payment Processing

PayFabric has several different endpoints depending on which version you are using.  When configuring Order Central, Account Central, or Sales Central, use the following endpoints based on the version you are setup to use:

LIVE V3
https://www.payfabric.com/Payment/API
https://www.payfabric.com/Payment/Web

LIVE V2:
https://www.payfabric.com/V2/Rest
https://www.payfabric.com/V2/web

TEST V3
https://sandbox.payfabric.com/Payment/API
https://sandbox.payfabric.com/Payment/Web

TEST V2:
https://sandbox.payfabric.com/V2/Rest
https://sandbox.payfabric.com/V2/web


TSheets Integration for Dynamics SL

 

Catalina creates seamless integration with TSheets and Dynamics SL.  This removes the tedious re-keying of data that introduces costly errors and additional resources.  The key Integration points are:

  • Synchronize Projects and Tasks between Dynamics SL and TSheets
  • Synchronize Employees between Dynamics SL and TSheets
  • Synchronize timecard entries between Dynamics SL and TSheets

This allows you to use a best of breed time tracking and approval software like TSheets.  And then be able to synchronize time back into Dynamics SL so that you can pay your employees and bill your customers.


SMS and Barcodes make for quick and easy communication to your ERP, Helpdesk, Field Service, or other system

SMS Central provides you with a way for customers and employees to quickly communicate information stored on barcodes directly back to your back-office systems by doing nothing more than taking a picture of the barcode and texting it.  You don’t need any app installed on a phone other than SMS messaging.  Those barcodes can then be used to create sales orders, service calls, inventory changes, as well as countless other things that you can use when tagging an item with a bar or QR Code.

Barcode formats SMS Central can handle

UPC-A, UPC-E, EAN-8, EAN-13, Code 39, Code 93, Code 128, ITF, Codabar, MSI, RSS-14, QR Code, Data Matrix, Aztec, PDF-417 

For Customers

Wouldn’t it be great if you could communicate information with high accuracy between you and your customers?  What if your customer has a problem with one of your products and you are trying to determine exactly which one it is?

SMS Central allows you to give your customer a phone number to SMS text to and mail a QR or barcode directly to your system already decoded!

All a customer has to do is take a picture of the barcode on their product and SMS message it to you.  They don’t have to install any special app on their phone and it will work on any phone.  SMS Central will then automatically decode that barcode and can then save it directly into your ERP, helpdesk, field service, CRM, or any other system so that you can have that information at your fingertips. 

For Sales

If you have sales people out in the field needing to restock shelves, supply restaurants, or other situation where the sales rep can snap a picture of the barcode on a product, SMS text it to your order management system, and then get it ordered.  All without any app installed on their phone.

Just snap a picture of a barcode of a product and send it to your order management or other system!

There are countless ways that SMS Central could be configured to handle most any workflow or need.

For Field Service, Inventory, and Asset Management

Your people in the field can quickly snap shots of barcodes and QR codes at customer sites to track what equipment is on site, what hardware has problems, or take inventory of assets at a location by simply using any phone and taking a picture and texting it.

Getting information about an asset or tracking assets is as easy as taking a picture of a barcode and sending it to your back-office system.  SMS Central does the rest!