If you are getting a timeout from the server (not the client) when calling Catalina’s APIs, what we generally recommend for our services is leaving the webservice debug flag set.
In the ctDynamicsSL/web.config file:
<compilation debug="true" batch="false" targetFramework="4.5"/>If the debug=”true” is in that file, then all server timeouts are already disabled and the issue is on your client.
Often, there is a problem when accessing the DMG’s, in Solomon, where you get an error “Missing Database information.” This is generally caused by a missing or invalid Solomon.ini file.
Validate that you have a good solomon.ini. Contact Catalina for a good solomon.ini file.
Looking at this, there are several things that are important
[System32 Database]
Server=servername\instance
Database=SYSDATABASE
DatabaseType=MS
[Company]
CompanyID=AVALIDCPNYID
UserID=SYSADMIN
Make sure you change the fields to match your installation
Minimum copy the files out to the following locations
your solomon application location
Windows directory
If the above doesnt fix it, then you will also need to locate where SL is trying to load the solomon.ini from.
Some versions of SL have a bug in the business objects that will throw this error when placing an order via CTAPI
The workaround for this error is altering the stored procedure DMG_TermsSelected and adding a blank string default value on the @SOBehavior variable.
Change:
@SOBehavior varchar(4),
To:
@SOBehavior varchar(4) = ”,
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:
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.
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.
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
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:
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:
There are a lot more API types of things in this blog category:
https://blog.catalinatechnology.com/category/catalina-api-for-dynamics-sl/
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 https://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.gitOr you can simply look at the full repository here: https://github.com/CatalinaTechnology/dotNETCore
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>It is easy to retrieve most any data from SL using Catalina’s API for Quick Query. Below is an example of how you can use SOAP and .NET to do this. This example shows yow you can retrieve subaccounts
First, you can also call the QuickQuery API via Postman (using the RESTful API) via below (NOTE: this should bring back all sub accounts since we arent filtering for anything.
curl --location --request POST 'http://YourServer.com/ctDynamicsSL/api/quickQuery/QQ_SubAccount' \
--header 'Accept: application/json' \
--header 'Authorization: Basic YOURAUTHORIZATION' \
--header 'CpnyID: YOURCPNYID' \
--header 'SiteID: YOURSITEID' \
--header 'Content-Type: application/json' \
--data-raw '{
"filters": [
]
}'Below is .NET code using SOAP. I had registered the SOAP web service quickQuery.ASMX and named it ctAPI.QuickQuery. This code shows you how you can retrieve subaccounts in 2 different ways
public void RunIt()
{
// call the web service, requesting the “QQ_SubAccount” quick query to be run. We will pass an empty filter array so that it will get everything
var returnWithoutFiltering = QuickQueryService.getScreen("QQ_SubAccount", new ctAPI.QuickQuery.queryFilter[0]);
{
// I like to convert to a JArray so that I can do other things with it. but lets loop through each row
Newtonsoft.Json.Linq.JArray myArry = Newtonsoft.Json.Linq.JArray.FromObject(returnWithoutFiltering.myQueryResults.Tables[0]);
foreach (var myVal in myArry)
{
Console.WriteLine($"SubAcct: {myVal["Subaccount"].ToString().Trim()}, Descr: {myVal["Description"].ToString().Trim()}");
}
}
Console.WriteLine();
// lets filter all sub accounts that contain the word "admin" in the description
var myFilters = new List<ctAPI.QuickQuery.queryFilter>
{
new ctAPI.QuickQuery.queryFilter {name = "Description", comparisonType = "LIKE", value="%admin%" }
};
// call the web service, requesting the “QQ_SubAccount” quick query to be run. Passing the myFilters array for filtering
var returnWithFiltering = QuickQueryService.getScreen("QQ_SubAccount", myFilters.ToArray());
{
// I like to convert to a JArray so that I can do other things with it. but lets loop through each row
Newtonsoft.Json.Linq.JArray myArry = Newtonsoft.Json.Linq.JArray.FromObject(returnWithFiltering.myQueryResults.Tables[0]);
foreach (var myVal in myArry)
{
Console.WriteLine($"SubAcct: {myVal["Subaccount"].ToString().Trim()}, Descr: {myVal["Description"].ToString().Trim()}");
}
}
}
private ctAPI.QuickQuery.quickQuery _quickQueryService = null;
public ctAPI.QuickQuery.quickQuery QuickQueryService
{
get
{
if (this._quickQueryService == null)
{
this._quickQueryService = new ctAPI.QuickQuery.quickQuery
{
Timeout = 300000,
ctDynamicsSLHeaderValue = new ctAPI.QuickQuery.ctDynamicsSLHeader
{
siteID = "YOURSITEID",
cpnyID = "YOURCPNYID",
licenseKey = "YOURLICENSEKEY",
licenseName = "YOUR LICENSE NAME",
licenseExpiration = "1/1/1900",
siteKey = "YOURSITEKEY",
softwareName = "CTAPI"
}
};
}
return this._quickQueryService;
}
set
{
this._quickQueryService = value;
}
}Below here is the data structure of a subaccount from the Quick Query QQ_SubAccount
{
"counter": 2,
"Subaccount": "01000CD00001 ",
"Description": "Administration-Canada ",
"Subaccount Status": 1,
"Consolidation Subaccount": "01000CD00001 ",
"Create Date": "1998-09-12T00:00:00",
"Create Program": "01270 ",
"Create User": "SYSADMIN ",
"Last Update Date": "1998-09-12T00:00:00",
"Last Update Program": "01270 ",
"Last Update User": "SYSADMIN ",
"NoteID": 0,
"User1": " ",
"User2": " ",
"User3": 0.0,
"User4": 0.0,
"User5": " ",
"User6": " ",
"User7": "1900-01-01T00:00:00",
"User8": "1900-01-01T00:00:00",
"totalEntries": 40,
"totalPages": 1,
"errorMessage": null
}
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;
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:
Once you have your licensekey, sitekey, and apikeyfile, you can run the ctConfigEditor tool.
So, in the above example, I have 4 users
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:
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:
