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:


Use PowerScript to Manage API Keys in Catalina’s RESTful API for Dynamics SL

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 (sales@catalinatechnology.com) if you are interested in receiving an early release.

Usage:

ApiKeyManager.ps1 -apikey <APIUsername> -sitekey <SiteKey> -xctfiles <xctfilesLocation> -apipass <password> -addapisites <SITE1,SITE2,SITE3> -delapisites <SITE1,SITE2,SITE3> -h -delete -list

Where

  • apikey: API Key to manage
  • sitekey: The encryption key used to encrypt connection strings and configurations
  • xctfiles: Root location of your xctfiles
  • addapisites: Comma Delmited list of sites to add to an API Key. Ex: ‘SITE1,SITE2,SITE3’
  • delapisites: Comma Delmited list of sites to remove from an API Key. Ex: ‘SITE1,SITE2,SITE3’
  • h: Help
  • delete: Will delete the key passed.
  • list: Will list the APIKeys. If a SiteID is passed, it will only list what was passed. If no siteID was passed (ex. ApiKeyManager.ps1 -list) it will list all APIKeys.

Examples

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'


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.


Warnings when running stored procedure script for Catalina’s API

When I run the script to install Catalina’s stored procedures, I get several messages like this:

The module ‘xct_spDSLXXXXXXXXX‘ depends on the missing object ‘xct_spDSLYYYYYYYYY‘. The module will still be created; however, it cannot run successfully until the object exists.

Don’t worry, those are not errors. They are just warnings that the stored procedure is referencing another stored procedure that hasn’t been created yet. It will get created later in the script.


Manage API Keys for Catalina’s RESTful API for Dynamics SL

You may want multiple users access Catalina’s API for Dynamics SL. When using the RESTful version of Catalina’s API, you can do this by managing the APIKEYSCONFIGFILE.xml (usually located on the web server at c:\inetpub\xctFiles\config — But could be somewhere else depending on the installation. Check with your installer)

NOTE: before doing any changes to Catalina configuration, make sure you backup the files you are updating first.

The APIKEYSCONFIGFILE.xml can be managed by a Catalina management tool called ctConfigEditor. (Normally located in C:\inetpub\xctFiles\ctConfigEditor — but could be in a different location based on installation). Once the ctConfigEditor is loaded, you will see a screen similar to this:

You will need to get your License Key and Site Key (found in the web.config file of the Catalina API for SL. — usually located c:\inetpub\xctFiles\web\ctDynamicsSL or c:\inetpub\wwwroot\ctDynamicsSL but could be located somewhere else based on installation). You will also need to point to the proper Config File.

Once you have loaded the APIKEYSCONFIGFILE.xml with the proper license key and site key, you will see a screen similar to this:

Here you can manage Authentication logins for the RESTful API. In the above example, there are 4 different keys. You can add new ones by just adding a line. and you can delete keys by clicking on the line item and hitting the delete key.

The columns of these API Keys are defined:

  • APIKey: the username of the authentication
  • SECRETKEY: The password of the authentication
  • SITES: a comma delimited list of sites the user has access to

(NOTE: A site is a configuration pointer. If you look at your DSLCONFIGFILE.XML file — usually in the same location as the APIKEYSCONFIGFILE.xml — you will see different Sites and SiteID’s. It is that SITE ID that you would put in the SITES column. If you want to give a user access to more than one site, you would then list all the sites comma delimited. Below is an example of what a DSLCONFIGFILE.XML looks like. You can see that there are two sites: LIVE and TEST.

Once you have finished editing your API Keys in the ctConfigEditor tool, you can then finish it and save by clicking on the “Finish” tab. You can click the Preview button to see what your APIKeys file will look like. You can also Save your file by clicking on the Save button.

Clicking on the save button will allow you to save to a file. You will need to save it on top of the existing APIKEYSCONFIGFILE.XML (NOTE: make sure you have this file backed up before overwriting it).

After you save the file, you will also need to reload your Application Pool in IIS to make the change stick.


Sending Information to Catalina Support

There are times that you might have questions or problems when developing using an API. You contact support and they will ask you to send you the “payload” you are using when communicating with the Catalina API for Dynamics SL. The easiest way to do this, if you are using Postman as your testing environment, is to export the code. This is done in these simple steps

Step 1:
Got to your postman tab you are making the API call from and click on the “Code” link on the right of the screen

Step 2:
On the popup, click on cURL and then copy the text provided, paste it into an email, and send to Support.


Debugging Catalina API for Dynamics SL

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"/>
  • DEBUGMODE: There are 2 different settings for this
    • TRUE if you want to have messages saved to a logfile.
    • FALSE if you don’t want to have messages saved to a logfile. Normally DEBUGMODE would be set to FALSE for performance reasons.
  • DEBUGLEVEL: There are 2 different levels that you can set
    • VERBOSE: This will save extra information to the logfile. This will create a larger file but will store more information about what is going on in the service.
    • BASIC: This generally stores just errors and less information
  • ERRORLOGFILE: This is the location of the logfile. NOTE: You need to make sure you “escape” this value. So, when you have a backslash (\), make sure you do 2 backslashes (\\) so that it wont create an invalid XML string.


Turn off Transactional Processing in Catalina’s API for SL

Catalina’s API for Dynamics SL wraps saving of data into transactions which allows for “rollback” if there is an error. Meaning if there are multiple tables/records that are in a transaction, and an error occurs, everything will get rolled back as if nothing happened.

There are some times when there are problems with this. Mainly when some type of external force (like a trigger) updates the same data that Catalina is trying to save. This could cause table locking and not allow transactions to save properly. One way to get around this is to turn transactional processing off.

NOTE: Only do this in a test environment first. This should be done if other methods don’t work.

This is done easily by changing the web.config of ctDynamics SL. Search for the keyword “DISABLETRANSACTIONS”.

Once you have found the keyword, make sure that the value=”TRUE” and that will turn off transactions.

<add key="DISABLETRANSACTIONS" value="TRUE"/>

If you only want to disable the transactions on a single web service and not all of Catalina’s API, Keep the value of DISABLETRANSACTIONS to FALSE. But add a key to web.config similar to this:

<add key="PROJECTCHARGEENTRYDISABLETRANSACTIONS" value="TRUE"/>

The above will only disable transactions for the Project Charge Entry web service. The syntax is like this:

<serviceName> + “DISABLETRANSACTIONS

So, if you wanted to disable transactions for customerMaintenance, the key would look like this:

<add key="CUSTOMERMAINTENANCEDISABLETRANSACTIONS" value="TRUE"/>


SL Quick Pay tips and tricks

Tips & Tricks for Catalina API for SL: Error Retrieving the COM class factory …

When you have an installation of Catalina’s API for Dynamics SL and you are receiving this error in your log files:

Err:Retrieving the COM class factory for component with CLSID {A440BD76-CFE1-4D46-AB1F-15F238437A3D}

This error is limited to SL7 installations and sometimes occurs during checkout or placing and order upon intial install of Catalina products; but usually after SL client updates or changes.

The problem is related to missing registry entry for: capicom.dll. This file is required by the the Microsoft Solomon components and used for database access. Capicom.dll is included in a variety of MS products and should already be located on the computer.

Common installation paths:
c:\program files\common files\microsoft shared\capicom.dll
C:\Program Files (x86)\Common Files\Microsoft Shared\CAPICOM\CapiCom.dll

If the file is not located there, we suggest doing a file system search for “capicom.dll”.

Once you have located the file on your server, you need to register it.

  • Pull up a command prompt and change to the directory where the capicom.dll file is located.
  • Enter: regsvr32 capicom.dll
  • Test your catalina install