Catalina Integrator – Catalina’s API Mapping Tool

Catalina Integrator – Catalina’s API Mapping Tool

The Catalina Integrator is a simple ETL tool that allows you to call API’s, transform the data, and send that data to other API’s.

In this demo, we are going to show how you can make a call to one of Catalina’s API’s and totally customize the API output so that you can then send it to another API or have it work for your specific client needs (mobile, web, etc).

This article is summarized in a video demo.  You can view the demo or read the details below. (NOTE:  the video is from a webinar and the capture is pretty poor.  That’s why I did a write-up to follow since most of the screens are barely visible in the video) Continue reading “Catalina Integrator – Catalina’s API Mapping Tool”

Example of building a Form Client to use the Catalina Quick Query SOAP Web Service

Example of building a Form Client to use the Catalina Quick Query SOAP Web Service

1.     In Visual Studio, we select the Visual C# Template for a Windows Form Application. Our client will be named: client.ctDynamicsSL.quickQuery.

ss1

Note: you can call the Catalina web services from any type of client that is able to make http/https calls, but for this example, we will use a Form Application.

2.     Add a reference to our Quick Query Web Service
a.     Right click on “References” and select “Add Service Reference” 

ss2

b.     On the “Add Service Reference” screen, click the “Advanced” button in the bottom left. (Image: qqcclient3.png)

c.      On the “Service Reference Settings” screen, click the “Add Web Reference” button. (Image: qqcclient4.png)

d.     On the “Add Web Reference” screen, enter in the URL to the web service. 

E.g.: http://localhost/ctDynamicsSL/quickQuery.asmx

Click the arrow button to discover the web service schema.

After the service definition loads, enter in a name to refer to this service in your client.

E.g.: ctDynamicsSL.quickQuery

ss3

e.     Click the “Add Reference” button.

f.       The new web reference will show up in your project.

ss4

 

3.     Create code to instantiate an object referencing our web service.

a.     I like to store values that are required in the Soap Header in the app.config file using System.Configuration, so we will first add a reference to the System.Configuration assembly. References -> Add Reference -> System.Configuration

ss5

b.     Create a private variable to store the actual object and a property to auto create the instance if the variable is null. This get{} property will pull the required header values from the app.config

ss6

Now whenever we want to call a function in the web service, we just reference it like so: myQQObj.functionName().

4.     Add the necessary elements for our main Form.

a.     TextBox for typing in a QueryViewName (tbQueryViewName)

b.     Button for a QueryViewName search (btnSearch)

c.      Button for executing our search (btnGetQuery)

d.     DataGridView for holding our search parameters (dgvFilters)

e.     ss7DataGridView for holding our search results (dgvQueryResults)

 

5.     Add a popup form for QueryViewName searches.

a.     The QueryViewName is the root of the Quick Query Service; they are names of SQL Views built in to SL. This is a required element, so let’s build an easy way to lookup them up.

b.     Add another Form object to the project: queryViewsPopup.cs

ss8.png

c.      Add a DataGridView to the new Form object.

d.     Click on the little arrow at the top right of the Grid and add ctDynamicsSL.quickQuery.vs_qvcatalog as the Data Source.

ss9.png

e.     For ease of use, edit the DataGridView Columns.

  • Move the QueryViewName column to the first position.
  • Change Name to “QueryViewName” we will use this to reference the cell later.

ss10

f.       On our main Form, tie an EventHandler to open this form.

g.      Add a CellDoubleClick Event Handler, to take the selected row and return the QueryViewName back to the tbQueryViewName on the main Form.

ss11.png

6.     Setup Filters DataGridView 

a.     The Quick Query Service getScreen call requires 2 parameters: queryViewName, filters[]. The filters parameter is of type: ctDynamicsSL.quickQuery.queryFilter.  

b.     The Filters is an array of triplets holding 3 required fields:

  • name – This must match the name of a column in the query view)
  • value – This is the value we are to filter/compare against)
  • comparisonType – This is any valid SQL comparison operator. E.g.: =, <, >, LIKE, IN, NOT IN

c.      Select the Data Source as ctDynamicsSL.quickQuery.queryFilter

ss12

7.     The Quick Query Service, is a V2 service by Catalina Technology and by design uses a screen() object for most calls that replicate the SL screen. Create a private variable to hold an instance of the screen object for all of our subsequent calls to the service.

ss13

8.     Write the code to call the web service, pass the parameters and tie the results to the Result DataGridView (dgvQueryResults)

ss14.png

9.     Test our Web Service Client:

a.     Find a Query View with our popup.

ss15

b.     Enter in some filters then Search and View the Results

ss16.png

 Note:     You can download the sample client Visual Studio Project at the following link: https://github.com/CatalinaTechnology/ctAPIClientExamples/tree/master/client.quickQuery

 

Catalina’s Queue Engine

Catalina’s Queue Engine

Catalina has a simple queuing engine that allows you to track changes on any table in SQL server. There is then an API that allows you to retrieve items that have been queued so that you can take action on them.  This is mostly done when you need to send Dynamics SL data, that has changed, to an outside system.

Example: A customer in Dynamics SL is modified in the SL Customer Maintenance Screen. You want to make sure that the customer terms, class, and other information makes it out to Salesforce.com (or other CRM system). Continue reading “Catalina’s Queue Engine”

How to call a custom SQL call using the Catalina API for Dynamics SL

How to call a custom SQL call using the Catalina API for Dynamics SL

How many times have you wanted to just make a SQL call from an app, website, or other system, but you don’t have direct access to a SQL connection or other easy method to call SQL?

Well the Catalina API for Dynamics SL has a secure way for you to make SQL calls over to your SL database using the Catalina common.asmx web service call.

Below is a quick tutorial on how to do this using .NET and the Catalina API for Dynamics SL (SOAP calls) Continue reading “How to call a custom SQL call using the Catalina API for Dynamics SL”

Using Swagger and Postman to test Catalina’s API for Dynamics SL (REST version)

Often, you don’t want to code out a client to run quick tests for an API.  Example, you might just want to retrieve a record or maybe you want to see what the return looks like when you post data to the API.  Writing a client can be a lot of work when all you need to do is just test things out.

You can do quick API calls by using Swagger and Postman.  This article is to show you how you can use Swagger to generate code so that you can then use the power of Postman to further test and work with the API. Continue reading “Using Swagger and Postman to test Catalina’s API for Dynamics SL (REST version)”

CTAPI – DEFAULTS & VALIDATIONS

CTAPI – DEFAULTS & VALIDATIONS

Catalina Technologies API for Dynamics SL allows you to create your own custom defaults and validations when sending data into SL through the API.

How to set Custom Defaults and Validations for web services in CTAPI. As of RELEASE builds post 2017/1/1, you are now able to overwrite defaults and validations in two single files. This is now the preferred place to make customizations, as it will avoid overwriting changes with new release builds of CTAPI.

The file for Defaults customizations is named: custom.default.ctDynamicsSL.xml and is located in your DEFAULTCONFIGDIRECTORY. (Path defined in your DSLCONFIGFILE, default: c:\inetpub\xctFiles\config\)
The file for Validations customizations is named: custom.validate.ctDynamicsSL.xml and is located in your VALIDATIONCONFIGDIRECTORY. (Path defined in your DSLCONFIGFILE, default: c:\inetpub\xctFiles\config\)
All customizations for defaults and validations for all CTAPI web services are contained in these two files.
Definition of the custom.default.ctDynamicsSL.xml file:

capture1

ID: (The field to set)
1. inItem – Always used to represent the Table/Object being defaulted. (not the field)
DEFAULTTYPE: (TEXT, PROC, CODE)
1. TEXT – sets the field value to the value listed in this xml element.
2 PROC – sets the field value to the value returned by the stored procedure listed in the xml element value. (optional: PARMS attribute listing stored procedure parameters)
3. CODE – sets the field value to the value returned by performing an eval on the code listed in the xml element value.

PARMS: (An optional, comma-delimitated list of parameters used for PROC Type defaults)
1. Variables from the inItem object that match stored procedure variable names.
e.g.: PARMS=’inItem.Status’
2. Rename an inItem object variable to a different stored procedure variable name.
e.g.: PARMS=’VendStatus=inItem.Status’
3. Hardcoded Stored procedure variable values.
e.g.: PARMS=’Active=1’

Definition of the custom.validate.ctDynamicsSL.xml file:

capture2

ID: (The field to set)
1. inItem – Always used to represent the Table/Object being defaulted. (not the field)
VALIDATETYPE: (LIST, PROC, NUMBERRANGE, DATERANGE, CODE)
1. LIST – a comma delimitated list of text values that are valid.
2. PROC – validates based on returnValue returned by the stored procedure listed in the xml element value. (optional: PARMS attribute listing stored procedure parameters)
3. NUMBERRANGE – a comma delimitated range of doubles.
e.g.: 1,5
4. DATERANGE – a comma delimitated range of dates.
e.g.: 1/1/2016,1/1/2019
5. CODE – validates the Boolean returned by performing an eval on the code listed in the xml element value.

PARMS: (An optional, comma-delimitated list of parameters used for PROC Type validations)
6. Variables from the inItem object that match stored procedure variable names.
e.g.: PARMS=’inItem.Status’
7. Rename an inItem object variable to a different stored procedure variable name.
e.g.: PARMS=’VendStatus=inItem.Status’
8. Hardcoded Stored procedure variable values.
e.g.: PARMS=’Active=1’

Introduction to CTAPI screen() Object

Most of the CTAPI Web Services are modeled after a counterpart SL client screen and intended to replicate its functionality.

The class path of these services matches the hierarchy and path to the screen in SL:

e.g.: ctDynamicsSL.financial.accountsPayable.maintenance.vendorMaintenance

screenmodel1-002

About the screen() object:

With this model in mind, all such services have a screen() object designed to match the schema of the comparable SL screen. E.g., In the Vendor Maintenance (03.270.00) SL screen, there is one SQL table referenced for reading and editing (Vendor).  This is represented by the myVendor variable of type ctDynamicsSL.Vendor inside the screen.  Also included is one read-only calculated object myBalances of type ctDynamicsSL.AP_Balances.

screenmodel2

Note: All object/table names and property/field names will match for both capitalization and naming.

Check mark.pngPro-tip: If you need to know which field to populate in the SL screen() objects, you only need to pull up Customization Mode in SL (Ctrl + Alt + C), locate the field and its name in the Property Window (F4), then find the FieldName. This FieldName correlates directly to a Table.Field and Object.Property in the screen() object.

e.g.: The following SL screen field correlates to:

ctDynamicsSL.financial.accountsPayable.maintenance.vendorMaintenance.screen.myVendor.Name

screenmodel3

In addition to the SL fields, all objects contain: public String errorMessage.

The errorMessage field defaults to a blank String “” and if populated, means that the system ran into an error during processing.

Note: when editing a screen object, any errors editing contained objects will bubble up to the screen level so it is only necessary to check the top object. 

 e.g.: if (!String.IsNullOrWhiteSpace(myScreen.errorMessage)){/*we ran into an error*/}

 Populating a screen object with defaults:

Every web service with a screen() object contains a public screen getNewscreen(screen inTemplate) call. This call will take the passed screen() object and return a copy with all default fields populated/overwritten.

Note: you can pass a null to get a completely new defaulted object.

e.g.: var myScreen = myVendorsService.getNewscreen(null);

Check mark.pngPro-tip: Some defaulted fields require other fields to be populated in order to get the right default value. E.g., CpnyID and CustID are common such fields; so it is recommend that you populate all non-defaulting fields before calling getNewscreen().

e.g.:
var myScreen = new ctDynamicsSL.financial.accountsReceivable.input.invoiceAndMemo.screen();
myScreen.myBatch = new ctDynamicsSL.financial.accountsReceivable.input.invoiceAndMemo.Batch();
myScreen.myBatch.CpnyID = “0060”;
myScreen = myIMObj.getNewscreen(myScreen); //loads defaults that depend on CpnyID

editScreen:

Every web service with a screen() object contains a public screen editScreen(String actionType, screen inScreen) call. This call is the workhouse used for Validations, Adding, Updating, or Deleting data.

The actionType parameter is standardized with:  VALIDATEONLY, ADD, UPDATE, or DELETE.

Note: you can leave actionType blank “” and the system will default to ADD if the primary keys do not already exist in the table, or UPDATE if they do. For best practices, always specify ADD or UPDATE.

e.g.:
//validate all my data before attempting to save:
var validateScreen = myVendorsService.editScreen(“VALIDATEONLY”, myScreen);
if (!String.IsNullOrWhiteSpace(validateScreen.errorMessage))
{
MessageBox.Show(“Error: ” + validateScreen.errorMessage);
return;
}

//add our new vendor entry
var add = myVendorsService.editScreen(“ADD”, myScreen);
if (!String.IsNullOrWhiteSpace(add.errorMessage))
{
MessageBox.Show(“Error: ” + add.errorMessage);
return;
}
else
{

//added our vendor, lets get the auto generated VendId
tbVendID.Text = add.myVendor.VendId.Trim();
}

//save our vendor screen updates
var update = myVendorsService.editScreen(“UPDATE”, myScreen);
if (!String.IsNullOrWhiteSpace(update.errorMessage))
{
MessageBox.Show(“Error: ” + update.errorMessage);
}
else
{
MessageBox.Show(“Save complete!”);
}