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.
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>
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:
When creating a purchase order using Catalina’s API for Dynamics SL and you get the following error:
“The create voucher flag cannot be changed once the document has been changed”
This is getting fired off because of a business rule violation. There is a work around. If you look in your DSLCONFIGFILE.xml, you should look for the following.
<CONFIGITEM ID='DISABLECREATEADONUPDATE' ENCRYPTED='False' COMMENTS=''>TRUE</CONFIGITEM>Make sure that the value of that CONFIGITEM is “TRUE”. If you don’t have this CONFIGITEM, add it to the site you are using via the SiteID. If you still have the problem after making this change, contact Catalina support to see if there is an update for your version of the API.
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:
If you need to set the authentication for Catalina’s API for Windows Auth to communicate to the SQL Server:
First you will need to update your connection strings in DSLCONFIGFILE.xml. You can see this from this blog post:
https://blog.catalinatechnology.com/2020/09/catalina-xml-configuration-file-editor-ctconfigeditor/
You will then need to change your sql connection strings
| Which Connection String | What 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.
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.
I did a demo on how to manage API Keys, for our RESTful API for Dynamics SL, using PowerScript. We are rolling out PowerScript management and installation tools for our products. Please contact us ([email protected]) if you are interested in receiving an early release.
ApiKeyManager.ps1 -apikey <APIUsername> -sitekey <SiteKey> -xctfiles <xctfilesLocation> -apipass <password> -addapisites <SITE1,SITE2,SITE3> -delapisites <SITE1,SITE2,SITE3> -h -delete -list
Where
If you want to get a listing, you would enter: ./ApiKeyManager.ps1 -h
Passing the -list parameter will get you something similar to this
If you want to create a new API Key with the username = “APIKEY1”, password = “Passw0rd1”, give access to 3 sites (“TEST”, “LIVE”, “DEVEL”), your SiteKey (encryption key) is “1234567”, and the location of your xctfiles is c:\inetpub\xctFiles, you would enter the below:
./ApiKeyManager.ps1 -apikey 'APIKEY1' -sitekey '1234567' -apipass 'Passw0rd1' -addapisites 'TEST,LIVE,DEVEL' -xctfiles 'c:\inetpub\xctFiles'If you wanted to delete the Site “TEST” from user “APIKEY” you would do something like this
./ApiKeyManager.ps1 -apikey 'APIKEY1' -sitekey '1234567' -delapisites 'TEST' -xctfiles 'c:\inetpub\xctFiles'If you want to delete the API Key ‘APIKEY1’, you would enter something like this:
./ApiKeyManager.ps1 -apikey 'APIKEY1' -sitekey '1234567' -delete -xctfiles 'c:\inetpub\xctFiles'There are several settings that you can set to log messages to a log file for Catalina’s API for Dynamics SL.
Look in your web.config (normally in c:\inetpub\xctFiles\web\ctDynamicsSL or c:\inetpub\wwwroot\ctDynamicsSL — but could be located in a different location based on your installation). There will be 3 variables that are important:
<!--def:DEBUGMODE: TRUE/FALSE default:FALSE-->
<add key="DEBUGMODE" value="TRUE" />
<add key="DEBUGLEVEL" value="VERBOSE" /><!--BASIC,VERBOSE-->
<!--def:ERRORLOGFILE: full path to the txt file to writeout error and status messages-->
<add key="ERRORLOGFILE" value="C:\\inetpub\\xctFiles\\errorLogs\\DSLerrorLogFile.txt"/>