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.
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
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:
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:
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
SET QUOTED_IDENTIFIER OFF
CREATE VIEW [dbo].[QQ_Brian]
CustId AS [Customer ID], Name AS [Customer Name]
FROM Customer with (nolock)
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
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.
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.
You will then need to change your sql connection strings
Which Connection String
What to Add
.NET Connection String
ODBC Connection String
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.
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@example.com) if you are interested in receiving an early release.
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’
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.
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:
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.
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.
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.