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.


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.


Custom Properties in SLQuickCollect

SLQuickCollect is Catalina’s solution that allows you to email or SMS message out a simple link to your customer as a request for payment.

Custom properties are a way to personalize the emails that go out to the customer. As well as the payment page and receipts they see. You can have an unlimited number of parameters with whatever text you want to send to the customer. And you can place it anywhere you want on the email and page templates.

Here is a quick demo on how you can do this via a RESTful API. And how to modify the templates to display the parameters.

Below is an example of a payload that you would send to the SLQuickCollect API.

{
    "parameters": [
        {
            "name": "CpnyID",
            "value": "0060"
        },
        {
            "name": "CustID",
            "value": "C300"
        },
        {
            "name": "Amount",
            "value": "10.23"
        },
        {
            "name": "PaymentEmailList",
            "value": "[email protected]"
        },
        {
            "name": "Properties",
            "value": "<nameValuePairs><key name=\"ORDNBR\" value=\"123456\"/><key name=\"COMMENTS\" value=\"Hi Ted, I appreciate your business.\"/></nameValuePairs>"
        }
    ]
}

There are several Parameters that are sent:

  • CpnyID: Your company ID in your SL system.
  • CustID: The Customer ID of the customer you are sending the payment request to.
  • Amount: The amount you want to collect
  • PaymentEmailList: A delimited list of emails that the request is going to go to.
  • Properties: This is a list of properties as Name/Value pairs. You can create as many of these properties as you want. And then you can display them in the email, payment page, receipt email, and receipt page templates any way you want.

When you want to display a custom property on a template page, you use this ASP.NET format:

<%=getProperty(“PropertyName“)%>

So, if the property name is “COMMENTS”, you would use this:

<%=getProperty(“COMMENTS“)%>


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


Call Stored Procedures Using Catalina’s API for Dynamics SL and Postman

It is simple to call a stored procedure through a RESTful API call if you have Catalina’s API for Dynamics SL. You can call any stored procedure and pass parameters and retrieve data.

This is a demo on how to call a stored procedure using Postman and Catalina’s API for Dynamics SL.

First, to do this demo, you need to download and install Postman. Postman is a developer tool that allows you to interact with API’s easily so that you can test API calls to see how you call them and what data is returned. You can get Postman here: https://www.postman.com/

In the demo, we are going to call the stored procedure SOHeader_all. This stored procedure retrieves all Sales Order Headers (SOHeader) for a particular CpnyID and OrdNbr. NOTE: this is just an example. With Catalina’s API, you can call any stored procedure.

SOHeader_all has 2 parameters:
– @parm1: This parameter is for the CpnyID
– @parm2: This parameter is for the OrdNbr (can use a wildcard like ‘O000%’ which will bring back all orders that start with O000.

You can see what the procedure looks like here:

PROCEDURE [dbo].[SOHeader_all]
	@parm1 varchar( 10 ),
	@parm2 varchar( 15 )
AS
	SELECT *
	FROM SOHeader
	WHERE CpnyID = @parm1
	   AND OrdNbr LIKE @parm2
	ORDER BY CpnyID,
	   OrdNbr DESC

So, if you wanted to retrieve all orders that started with “O000” for CpnyID = “0060” you would call the stored procedure like this:

exec SOHeader_all @parm1='0060', @parm2='O000%'

So, now how to call this using Postman through Catalina’s API for SL?

First you need to know where your Catalina API is installed. I am going to use the server name yourserver.com as the domain name. So, for this example, we would look at the endpoint as the following:

http://yourserver.com/ctDynamicsSL/api/customSQL/<ProcedureName>

As you can see above, you would replace yourServer.com with wherever your server is. And you can see <ProcedureName> in the URL. this would be replaced with the actual stored procedure name you want to call (in this example, we are going to replace it with SOHeader_all). So, the new URL for the endpoint would look like the following:

http://yourserver.com/ctDynamicsSL/api/customSQL/SOHeader_all

In Postman, you would make it look like below. NOTE: when calling a customSQL stored procedure, you must use the action type of “POST”

Next, you need to set the authentication. This is done on the “Authorization” tab. Catalina’s API uses “Basic Auth”. So, make sure that you set the type for “Basic Auth” in the dropdown. And then enter the username and password that was given to you from your installer.

After that, you will have been given a SiteID from your installer. You will need to create a Header for that SiteID. You do this on the headers tab. You should enter that SiteID (in my example it is “DEFAULT”, but you would use the SiteID given to you by your installer) and the default CpnyID (in my example that is “0060”, but you would use your CpnyID of your database)

Finally, you will want to enter the body of the parameters that are being passed. There are 2 parameters for SOHeader_all (@parm1 and @parm2). The format of the body that you would set is below.

{
    "parameters": [
        {
            "name": "parm1",
            "value": "0060"
        },
        {
            "name": "parm2",
            "value": "O0005121"
        }
    ]
}

So, your Body tab in Postman would look like this (NOTE: make sure you select the “raw” radio button as shown below)

Then all you have to do is simply hit the “Send” button and the system should retrieve the results from your stored procedure call. In my example, it looks like below


Create a Contact Free Payment Solution for Dynamics SL (Mobile App)

This is a demo that shows you how to create a mobile app to interact with Dynamics SL to provide a “Contact Free” payment solution to help protect your employees and customers during COVID 19. The intended user of this example app would be a customer service rep, sales person, or field service rep who needs to collect payment from a customer (handy for collecting a deposit or down payment before delivery, installation, or service work to be done).

This demo uses Catalina’s API to search customers in SL and then lets the user to request a payment from a customer by generating a link and emailing it to the chosen customer. That customer then can click on the link and pay the amount which automatically creates a payment in SL’s AR.

NOTE: Source code for the mobile app can be found on Github here: https://github.com/CatalinaTechnology/SL-Mobile/tree/main/ctPayment

Check out the video of the demo on our Youtube channel here:

Below is a screenshot of the Android app from the above demo. First you can search for a customer by a keyword. That search will then bring back a list of results. You can then click on the customer you want to request funds for. The app will automatically fill in the email address of the customer (from the Customer record in Dynamics SL). You can change the email address if you want. You then enter a requested payment amount and hit submit. Once you do this, Catalina’s SLQuickCollect will send off an email to the customer with a link which will then allow them to make a PCI compliant secure payment. Once authorization occurs, SLQuickCollect will then create a payment in Dynamics SL automatically.

As mentioned below, if you want to have starter code on creating an Android App (with Visual Studio and Xamarin), you can check out an example on our Github here (NOTE: I would only consider this a starter. This is in no means something finished but enough to get you started)

https://github.com/CatalinaTechnology/SL-Mobile/tree/main/ctPayment


EDI Integration with Dynamics SL Using Catalina

If you need EDI integration between your trading partners and Dynamics SL, you can use Catalina’s API for SL to get data in and out of Dynamics SL. One of the simplest of transactions is order management. If you have a trading partner that needs to send you PO’s so that you can then fulfill, the most common documents used are:

  • Inbound Documents
    • 850: This is a purchase order to fulfill
  • Outbound Documents
    • 855: An immediate response sent back to your trading partner acknowledging that you received the transaction
    • 997: An acknowledgement that you have received the transaction and often when you will pass back a reference number for your internal order number
    • 856: A shipper notification that notes what has shipped on the PO when a shipper is generated

The key to this is a data mapping layer that allows you to translate the inbound EDI documents and transform it into something that the Catalina API can understand. The reverse is true when data needs to be sent from SL out to your trading partner. The Catalina API will retrieve the data and then the translation will transform that data into an EDI document to send back to your customer.

If you have questions or need assistance with EDI integration with DynamicsSL, you can contact Catalina at [email protected]