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

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.

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

Pro-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

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);

Pro-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!”);
}