Retrieving and Saving Customers in SL using Catalina’s API for Dynamics SL

Retrieving a Customer

Retrieving a customer is quite simple. You would perform a GET from Catalina’s API (REST) using the following endpoint: /api/financial/accountsReceivable/customer/{CustID}

Example, if you wanted to retrieve customer C300, you would use this endpoint: /api/financial/accountsReceivable/customer/C300

A curl example would be as follows:

curl --location --request GET 'http://YOURSERVER/ctDynamicsSL/api/financial/accountsReceivable/customer/C300' \
--header 'Authorization: Basic YOURAUTH' \
--header 'Content-Type: application/json' \
--header 'CpnyID: YOURCPNYID' \
--header 'SiteID: YOURSITEID'

To do this retrieve in Postman, it would look similar to this:

Saving a New Customer

If you want to save a new customer, you would perform a POST to the following endpoint: /api/financial/accountsReceivable/customer (NOTE: you would NOT post a custID in the URL of the endpoint)

Below is a minimum curl POST that will create a customer. NOTE: if you do not pass a CustID in the request body, SL will automatically select a CustID for you. Also NOTE that if you try to do a POST and pass a CustID in the request body that already exists, the system will give you an error stating that you cant create a new customer with an existing CustID.

curl --location --request POST 'http://YOURSERVER/ctDynamicsSL/api/financial/accountsReceivable/customer' \
--header 'Authorization: Basic YOURAUTH' \
--header 'Content-Type: application/json' \
--header 'CpnyID: YOURCPNYID' \
--header 'SiteID: YOURSITEID' \
--data-raw '{
  "myCustomer": {
    "Name": "Fred Flintstone",
    "Addr1": "333 Smith Street",
    "Addr2": "",
    "City": "Boston",
    "State":"MA",
    "Zip": "02108",
    "ClassId": "HEALTH"
  }
}'

If the POST is successful, the API will pass back the newly saved customer. In the response body, you will see the field myCustomer.CustId. That will be the CustID saved (if you passed a valid CustID or if the system automatically set the CustID if you didn’t pass one in the request body)

It would like like this in Postman:

The customer can now be viewed in the SL Customer Maintenance (08.260.00) Screen.

Updating a Customer

If you want to change a customer, you would make a PATCH call to the following endpoint: /api/financial/accountsReceivable/customer/{CustID}

NOTE: you would replace {CustID}, in the URL, with the Customer ID you want to update. So, if you want to update customer 00128, the endpoint would look like this: /api/financial/accountsReceivable/customer/00128

Regarding the request body, you would only pass the fields you want changed. If you want to change the customer’s name, but you don’t want to change anything else, then only pass the Name field with the value you want to change. So, if I wanted to change customer 00128 to have the customer name of “Barny Rubble” instead of “Fred Flintstone,” I would do a call something like this:

curl --location --request PATCH 'http://YOURSERVER/ctDynamicsSL/api/financial/accountsReceivable/customer/00128' \
--header 'Authorization: Basic YOURAUTH' \
--header 'Content-Type: application/json' \
--header 'CpnyID: YOURCPNYID' \
--header 'SiteID: YOURSITEID' \
--data-raw '{
  "myCustomer": {
    "Name": "Barny Rubble"
  }
}'

If you did this in Postman, it would look similar to this (see how I used a PATCH and only passed the Name and nothing else):

You can then refresh the customer in the SL Customer Maintenance Screen and see the change.


Using Catalina’s API for Dynamics SL

For developers, our SOAP version has the definition of this in the WSDL here (NOTE:  we have it separated by function/module depending on what you need to do):

https://www.catalinatechnology.com/ctapi/services/ctDynamicsSL

If you are using RESTful API, we have swagger documentation here:

https://www.catalinatechnology.com/ctapi/services/ctdynamicssl/swagger

We have a lot of SOAP examples on our GitHub samples repository here (if they are using SOAP): https://github.com/CatalinaTechnology/ctAPIClientExamples

I also have quite a few demos on YouTube

Using RESTful API

If you are using RESTful API, here is a decent demo that I did that shows how to utilize Swagger and Postman to integrate to SL through our API:

This is a playlist of more of our API demos here:

We also have a lot of examples of things on a blog.  You can see here how to create sales orders using our RESTful API:

 http://blog.catalinatechnology.com/2019/02/creating-sales-orders-in-sl-using-catalinas-api-for-dynamics-sl/

There are a lot more API types of things in this blog category:

http://blog.catalinatechnology.com/category/catalina-api-for-dynamics-sl/


Using Catalina’s RESTful API for Dynamics SL in Dotnet Core

Many are starting to use dotnet core as a development environment for many reasons. It is compact, you can easily deploy to Docker containers, you can run cross platform, and many other reasons.

We get a lot of questions on how to use our API, for Dynamics SL, in a dotnet core environment.

You can see an example of dotnet core and Catalina’s RESTful API for Dynamics SL here: https://github.com/CatalinaTechnology/dotNETCore/tree/master/RESTExample

We have a previous demo on how to use our SOAP web services with dotnet core here http://blog.catalinatechnology.com/2020/01/access-catalinas-api-for-dynamics-sl-using-net-core/

If you want to be able to do something with our REST API or SOAP Web services, you may need to have a place to start. If you check out our github dotNETCore repository, you can see examples of both. You can clone the repository using the git client:

git clone https://github.com/CatalinaTechnology/dotNETCore.git

Or you can simply look at the full repository here: https://github.com/CatalinaTechnology/dotNETCore


SL Quick Pay tips and tricks

Calling Custom Stored Proc in Catalina API gives Checksum Error

If you are trying to make a call to a custom stored procedure, you may get an error back like the following:

{
    "errorMessage": [
        {
            "errorMessage": "Message - Failed CheckSum!\nTrace -    at ctDynamicsSL.lib.common.customSQLCall(String sqlCall, nameValuePairs[] inParms, String checkSum)\nSource - ctDynamicsSLLib\n"
        }
    ]
}

This is because Catalina’s API has security where you need to create a hash and pass that hash of the name of the stored procedure (using the same APIKey setup in ctDynamicsSL) so that when the API retrieves your request for the SQL call, it is using the same shared key for the hash encryption.

If you don’t want to do this, you can look at your DSLConfigFile.xml file. Look in the XML block denoted by the SiteID you are using in your header and make sure that this line is there (with the value = TRUE — All Caps). This will disable that checksum check.

<CONFIGITEM ID='DISABLESQLCHECKSUM' ENCRYPTED='False' COMMENTS=''>TRUE</CONFIGITEM>


Connection was Forcibly Closed with Catalina API

SL Quick Pay tips and tricks

If you are connecting to one of Catalina’s API endpoints (either REST or SOAP) and you are using https://, if you get an error saying the “Connection was Forcibly Closed,” this is normally because the web server requires a specific TLS version and your client isn’t using that.

If you are writing this in .NET, this can be easily overcome by adding this statement before you make a call to our API (it is normally fine to put it in the constructor or in some startup routine):

System.Net.ServicePointManager.SecurityProtocol = 
   System.Net.SecurityProtocolType.Tls12 
   | System.Net.SecurityProtocolType.Tls11 
   | System.Net.SecurityProtocolType.Tls 
   | System.Net.SecurityProtocolType.Ssl3;

Tips and Tricks using BASIC auth for REST

RESTful API Authentication for Catalina’s API for SL

Catalina’s RESTful API for Dynamics SL uses BASIC authentication. You can manage your authentication using Catalina’s ctConfigEditor.exe tool. This is normally installed on the API Web server in the c:\inetpub\xctFiles\ctConfigEditor folder. It may be different on your server so you may need to contact your IT administrator. The executable is ctConfigEditor.exe.

You will first need a few pieces of information from the web.config file of your ctDynamicsSL folder (the location where Catalina’s web services/API resides). The folder is normally located at: c:\inetpub\xctFiles\web\ctDynamicsSL. But could be in another location based on your server setup. You may need to contact your IT administrator to find out where it is.

Looking in the web.config, you should see several keys in the appSettings section that is required for ctConfigEditor to be able to read your authentication file:

  • LICENSEKEY
  • SITEKEY
  • APIKEYFILE

Once you have your licensekey, sitekey, and apikeyfile, you can run the ctConfigEditor tool.

Make sure you have the radio button “Modify Existing APIKEY File” as shown above. Then enter the APIKEYFILE in the Config File text box, the LICENSEKEY in the License Key text box, and the SITEKEY in the Site Key text box. Then you can press the “Next” button to be able to enter your API Keys for BASIC authentication.
You can now edit/add/delete users for access to the system. There are 3 fields for each user:
  • APIKEY: this is the username that the user would be using in the RESTful API basic authentication
  • SECRETKEY: this is the password that the user would be using in the RESTful API basic authentication
  • SITES: This is a comma delimited list of sites the user can access

So, in the above example, I have 4 users

  • TESTINGUSER: This user can only access the TEST site
  • LIVEUSER and LIVEUSER2: These users can only access the LIVE site
  • DEVELUSER: this user can access both the LIVE and the TEST site

NOTE: Sites are basically configurations in Catalina’s API that point to different database strings and configurations. If you look in your web.config file, of the ctDynamicsSL folder, you can see an appSettings key called DSLCONFIGFILE. This is the location of a configuration file that has all the different sites setup. Below is an example of what a DSLCONFIGFILE would look like. You can see that there are 2 separate sites. Each with their own connection strings and configurations.

NOTE: Do not change your DSLCONFIGFILE unless you intend to change settings. This tutorial is NOT about DSLCONFIGFILE but about your API Keys.

So, now that we have our API Keys setup, lets do an example. If we want to use the following:

  • Use the TESTINGUSER API Key (with it’s password of “#5f8btpz@$S$viB#TVfJ”)
  • We are going to use the TEST SiteID
  • We will have a server name of yourserver.com
  • We want to retrieve the Customer “C300” from SL using the customer endpoint

The curl code would look the following:

curl --location --request GET 'http://yourserver.com/ctDynamicsSL/api/financial/accountsReceivable/customer/c300' \
--header 'SiteID: TEST' \
--header 'Authorization: Basic VEVTVElOR1VTRVI6IzVmOGJ0cHpAJFMkdmlCI1RWZko='

NOTE: to create the authorization string, you would take the username and the password and create a string like this: “TESTINGUSER|#5f8btpz@$S$viB#TVfJ” and then base64 encode it. You will get the following value: VEVTVElOR1VTRVJ8IzVmOGJ0cHpAJFMkdmlCI1RWZko=

To create the header for “Authorization.” Take the base 64 encoded value and put “Basic” in front of it. Your end result would be the following: “Basic VEVTVElOR1VTRVJ8IzVmOGJ0cHpAJFMkdmlCI1RWZko=”

Looking at it in Postman looks like the following:


Solving Problem with Retrieving Data in REST with a Period in the ID

What happens if you are using Catalina’s API for Dynamics SL and your ID you are searching for (example a CustID, Vendor ID, etc) has a period in it? It will fail with standard installation. This is because the .NET web application is looking for a period in the final parameter so that it can route.

You will get a return that looks something like this with a 404 status and HTML coming back:

This can be solved by changing the web.config.

NOTE: if you make this change, then you wont be able to run SOAP and REST in the same application. SOAP will stop working and you would need to install a separate instance with it’s won web.config to make this work.

If you look in the Web.config, you will see the following line:

<add name="ExtensionlessUrlHandler-Integrated-4.0" path="*." verb="*" type="System.Web.Handlers.TransferRequestHandler" preCondition="integratedMode,runtimeVersionv4.0" />

NOTE how the path=”*.” Has a period in it.  Remove it and make it look like this:

<add name="ExtensionlessUrlHandler-Integrated-4.0" path="*." verb="*" type="System.Web.Handlers.TransferRequestHandler" preCondition="integratedMode,runtimeVersionv4.0" />

This will break SOAP.  But should work.  I created a vendor with a vendor ID of B.WHARTON and then ran this:

curl --location --request GET 'http://catalina.local/ctDynamicsSL/api/financial/accountsPayable/vendor/B.WHARTON' \
--header 'Accept: text/html' \
--header 'Authorization: Basic MY_AUTH_HERE' \
--header 'CpnyID: 0060' \
--header 'SiteID: DEFAULT'

This worked fine:


How to add a Quick Query in SL without using Quick Query (for Catalina’s API)

Ok, so using Catalina’s API for Dynamics SL makes it easy to get data out of SL through it’s quick query endpoint (/ctDynamicsSL/api/quickQuery). But what if you really don’t actually use QuickQuery in SL. But you still want to use it in Catalina’s API? Easy, just create your view and then add a reference to it in QVCatalog table in your System Database.

Step 1: Creating the View

What I first am going to do is create a view in my Application Database. This will be a simple view that will retrieve customers. And only retrieve the CustID and Customer Name. Below is the SQL code to create my view named QQ_Brian.

/****** Object:  View [dbo].[QQ_Brian]  ******/
SET ANSI_NULLS ON
GO
SET QUOTED_IDENTIFIER OFF
GO
CREATE VIEW [dbo].[QQ_Brian]
AS
SELECT	
     CustId AS [Customer ID],  Name AS [Customer Name]
FROM	Customer with (nolock)

GO

Step 2: Create a Reference to the View in QVCatalog

Next step is to insert a record into the QVCatalog table to reference the view. This table will be in your System Database. Below is what my insert looked like

INSERT INTO QVCatalog
(SQLView,BaseQueryView,QueryViewName,Module,Number,ViewDescription,ViewFilter,ViewSort,ColumnsRemovedMoved,DrillPrograms,VisibilityType,Visibility,SystemDatabase,CompanyColumn,CompanyParms,CreatedBy)
VALUES
(
	'QQ_Brian',
	'QQ_Brian',
	'QQ_Brian',
	'01',
	'QQBRIAN',
	'Your Description Here',
	'<criteria><or /></criteria>',
	'',
	'',
	'',
	0,
	'',
	0,
	'',
	0,
	'[DynamicsSL]'
)

Looking at the above insert statement, you see where I am using the name of my view (QQ_Brian) for SQLView, BaseQueryView, and QueryViewName. I am also using QQBRIAN as my number. You would change these values to what your view name is. I also entered a description (“Your Description Here”). Set that value to something that will allow you to remember what this view does.

Testing it!!!

Now all you have to do is test it. here is some curl code that shows you what I did to test my view in the Catalina’s API for SL, using Postman and our RESTful API for SL.

curl --location --request POST 'http://yourServerHere/ctDynamicsSL/api/quickQuery/QQ_Brian' \
--header 'Accept: application/json' \
--header 'Authorization: Basic YOURAUTHHERE' \
--header 'CpnyID: YOURCPNYHERE' \
--header 'SiteID: YOURSITEIDHERE' \
--header 'Content-Type: text/plain' \
--data-raw '{
    "filters":[
        {
        }
    ]
}'

Because you aren’t adding any filtering, the above curl will bring all records back. You can try this in Postman like below:

If you want to get fancier, you can add some filtering like this to limit the return (you can see more information about filtering and using Catalina’s API here: http://blog.catalinatechnology.com/2019/03/tips-tricks-on-using-catalinas-quick-query-api-to-get-the-data-you-want-out-of-a-sql-database/)

Below is code to show how you can use your custom QuickQuery view and filter it by Customer ID (CustID):

curl --location --request POST 'http://yourServerHere/ctDynamicsSL/api/quickQuery/QQ_Brian' \
--header 'Accept: application/json' \
--header 'Authorization: Basic YOURAUTHHERE' \
--header 'CpnyID: YOURCPNYHERE' \
--header 'SiteID: YOURSITEIDHERE' \
--header 'Content-Type: text/plain' \
--data-raw '{
    "filters":[
        {
            "name": "Customer ID",
            "value": "C300",
            "Comparison": "="
        }
    ]
}'

The above curl code will bring back all records that have the “Customer ID” field equal to “C300” (in my case, There Can be Only One). You can see what it would look like in Postman here:


Setting Identity for Windows Auth For Catalina API

If you need to set the authentication for Catalina’s API for Windows Auth to communicate to the SQL Server:

Editing the DSLCONFIGFile connection Strings

First you will need to update your connection strings in DSLCONFIGFILE.xml. You can see this from this blog post:

http://blog.catalinatechnology.com/2020/09/catalina-xml-configuration-file-editor-ctconfigeditor/

You will then need to change your sql connection strings

Which Connection StringWhat to Add
​.NET Connection String;Trusted_Connection=True;
​ODBC Connection String;Integrated Security=SSPI;

For both of these strings, you would remove the username and password from the strings and add the trusted_connection=True for the .NET connection string. And you would add the Integrated Security=SSPI for the ODBC connection string.

Configure the IIS Application Pool for the Identity

Next, you would go into IIS manager and click on Advanced Settings, look at “Identity” and click on the 3 dots button.

Then choose the “Custom Account” radio button and press the “Set” button.

Another popup will be displayed and you are then able to put in the username (replace the example below with your domain\username) and password. After you press OK, the system will tell you whether it is valid or not. NOTE: You will need to make sure that the user has access to the SQL objects in SQL server.


Advanced Rules Based Integration with Catalina API for SL

Catalina’s API for Dynamics SL can be used for many things. We can retrieve all types of data from SL. We can also save transactions to SL. In this demo I did for several folks, I am taking sensor data and pushing it through an advanced rules based engine to create Service Calls in Dynamics SL.

While this demo highlights Dynamics SL, we could just as easily use these same types of rules based development to integrate with other systems like CRM, helpdesk, field service, etc. We can monitor all types of things like temperature, barometric pressure, vibrations (helpful if you an HVAC company and need to monitor your customer’s properties for problems), humidity, ambient light, flooding, and more.