Programming with eBusiness Web Services

eBusiness Web Services provides a platform independent programming interface. Any programming language in any development environment and operating system that has support for SOAP, WSDL, and HTTPS can be used to call eBusiness Web Services.

How a particular environment invokes the web services operations from a programming perspective, is not defined by web services; therefore, we cannot document how to call eBusiness Web Services from all possible development environments. For examples of calling eBusiness Web Services from some popular environments, see Quick Start.

All eBusiness Web Services operations are stateless and atomic. An operation either completes successfully or does not complete at all. For example, if a network connection is dropped during the CreateSalesOrder operation, and a sales order has been partially transmitted, the operation will not create a partial sales order; it will not create a sales order at all.

eBusiness Web Services operations must be called from a SOAP client. How the client is created depends on the development platform, but all clients must point to the URL where eBusiness Web Services resides.

eBusiness Web Services operations utilize SOAP faults when they error. The development environment for the client application determines how to capture and handle the faults. Most environments require that SOAP faults be handled by catching exceptions through the use of try/catch blocks.

For instructions on creating a SOAP client and for examples of how to use try/catch blocks for some popular development environments, see Quick Start.

Web Services Description Language (WSDL)

eBusiness Web Services uses the WSDL standard to describe the services it provides. The use of WSDL allows a programmer to point to the URL where eBusiness Web Services resides and begin programming against the web services. The programmer does not need to concern themselves with forming proper SOAP/XML requests when using a development platform capable of consuming WSDL.

eBusiness Web Services provides two sets of WSDL:

Full: Targeted for Microsoft Visual Studio Service Reference (sometimes referred to as a WCF client).
Basic: Targeted for all other environments, including Microsoft Visual Studio's Web Reference, Java's JAX-WS client, and PHP’s integrated SoapClient.

The WSDL that a client obtains is determined by the entry point of the URL. eBusiness Web Services provides two default entry points:

MasService.svc - Full WSDL
MasBasicWsdl.svc - Basic WSDL

Administrators can define other entry points by using the advanced options in the Sage 100 eBusiness Web Services configuration utility.

Choosing the appropriate WSDL to consume will help ensure that the client application generates efficient SOAP requests and will help reduce the complexity of any generated proxy classes.

For example, a Visual Studio developer can point a Service Reference to https://server/ebusinesswebservices/masservice.svc?wsdl while a Java developer can point JAX-WS to https://server/ebusinesswebservices/masbasicwsdl.svc?wsdl.

Using SOAP Efficiently with eBusiness Web Services

eBusiness Web Services uses the W3C standard SOAP protocol to communicate between the client and server.

It is the use of SOAP that helps ensure that requests can traverse the Internet and that operations can be called from numerous platforms such as PCs, PDAs, and SmartPhones.

SOAP is an XML based protocol and; therefore can be quite bandwidth intensive if not used with care. eBusiness Web Services can be configured and programmed to reduce the amount of bandwidth used.

For example, as part of the response from a call to the GetCustomer operation, the following snippet of XML may be sent:

<Customer xmlns="http://mas90.sage.com/ws"

xmlns:i="http://www.w3.org/2001/XMLSchema-instance">

<AddressLine1>2131 N. 14th Street</AddressLine1>

<AddressLine2>Suite 100</AddressLine2>

eBusiness Web Services can be configured to not emit XML for empty strings and zero values in server responses. When configured with these options, the above snippet would appear as follows:

<Customer xmlns="http://mas90.sage.com/ws"

xmlns:i="http://www.w3.org/2001/XMLSchema-instance">

<AddressLine1>2131 N. 14th Street</AddressLine1>

<AddressLine2>Suite 100</AddressLine2>

As the example demonstrates, bandwidth is significantly reduced when the data returned contains many empty strings and zero values. A side effect of not emitting empty strings and zero values is that these values will appear as null values at the client. The client application must be able to process the null values returned to it.

eBusiness Web Services also allows specific fields to be blocked for read operations. When a field is blocked, XML for the field is never emitted. Blocking fields will generally yield the most bandwidth reduction, but care must be taken not to block fields that either the client application or eBusiness Web Services require to function properly. The eBusiness Web Services reference section can be used to determine the fields required for a particular operation. For more information, see APIs.

eBusiness Web Services has no control over XML generation at the client. Reducing bandwidth for client requests is the sole responsibility of the client application. Most development platforms will not emit XML for a Sage 100 entity field if the field value is set to null. Setting unneeded fields to null at the client is generally the most effective way of reducing bandwidth in client requests.

Date and Time Values

Sage 100 systems natively store dates and times in separate fields. eBusiness Web Services converts these separate fields into one field that returns the SOAP standard DateTime type.

For example, native Sage 100 Standard sales orders contain the following two fields in the payment object:

AuthorizationDate$
AuthorizationTime$

eBusiness Web Services converts these two fields into a single field called: AuthorizationDateTime

Some native data in Sage 100 systems have only a date component. For example, the sales order OrderDate$ field has no corresponding time field. Sage 100 will still return these fields as a DateTime type, but will distinguish date-only fields from date-time fields by omitting "Time" from the field name. In the case of OrderDate$, eBusiness Web Services exposes this field as OrderDate rather than OrderDateTime.

When a date and time is blank in Sage 100, null will be returned by eBusiness Web Services when the date and time are read through a Get operation.

Update and Create operations treat null values as "not set"; eBusiness Web Services performs no operation at all for a field when it is null. Setting a DateTime value to null during an Update operation will not set the Sage 100 date and time to blank. Instead, a special NullDateTime value must be used. This value can be obtained by calling the GetContractInformation operation. This value is constant and only needs to be obtained once by the client application.

Credit Card Processing

Credit card processing has changed significantly from previous version of eBusiness Web Services. It no longer allows eBusiness Web Services to enter a credit card number and CVV code directly into the SalesOrder contract because it no longer contains these fields. Instead, the SalesOrder contract contains a CreditCardGUID field that corresponds to a credit card number stored in the Sage Exchange Vault. In addition, the Payments collection of the SalesOrder contract contains CreditCardTransactionID and CreditCardAuthorizationNo fields that relate to a pre-authorization performed on a credit card.

The AddCreditCardToVault operation adds a credit card number and expiration date to the Sage Exchange Vault. This method will return a credit card GUID that should be stored by the calling application for future use. For more information, see AddCreditCardToVault.

A PreAuthorizeCreditCard operation explicitly pre-authorizes a credit card by the calling application. This call must be used to process a credit card using a CVV code. The operation will return a PreAuthorizationResult contract that contains the fields CreditCardTransactionID and CreditCardAuthorizationNo. The values in these fields, along with the credit card GUID obtained from AddCreditCardToVault , may be set in the Payments collection of the SalesOrder contract submitted to the CreateSalesOrder or UpdateSalesOrder operation to attach the pre-authorization to the sales order for an eventual completion of payment in Sage 100. For more information, see PreAuthorizeCreditCard.

As a security feature, credit card numbers and CVV codes are never returned by eBusiness Web Services.

UDFs and Development Partner Fields

UDFs and Development Partner fields are not exposed by default. UDFs can be automatically exposed by setting the AutoExposeUDFs option to Yes in eBusiness Web Services - Advanced Settings. UDFs and Development Partner fields can also be selectively exposed by adding them to the eBusiness Web Services - Advanced Settings Additional Fields tab. Development Partner fields cannot be automatically exposed; they must always be defined in the Additional Fields tab.

Both UDFs and Development Partner fields are exposed in the OtherFields collection of an entity. OtherFields contains a collection of Field objects. The Field object contains two fields:

MasFieldName: The name of the UDF or Development Partner Field (for example, "UDF_NICKNAME$")
Value: The value of the UDF. Value is always a string type, even when the native type for the field in the Sage 100 system is numeric.

To read a field, the OtherFields collection must be iterated through and MasFieldName compared against the desired field name before reading the Value field. Do not to assume that a particular field will always be at the same index position in the collection.

To change a field value for an Update operation, the OtherFields collection must be iterated through and MasFieldName must be compared against the appropriate field name before setting the field's Value field. The appropriate field may not be found if it has been explicitly blocked for read access in the advanced configuration settings. If this is the case, and write access is allowed for the field, a new Field object must be added to the OtherFields collection with MasFieldName and Value set to their appropriate values.

To set a field value during a Create operation using an entity instantiated at the client, a new Field object must be added to the OtherFields collection with MasFieldName and Value set to their appropriate values. The OtherFields collection will also need to be instantiated using the appropriate collection type for the platform.

For example, to set UDF_NICKNAME$ before calling CreateSalesOrder, the following C# code can be used with a Microsoft Service Reference:

masws.SalesOrder salesOrder = new masws.SalesOrder();

salesOrder.OtherFields = new BindingList<masws.Field>();

masws.Field udfField = new masws.Field();

udfField.MasFieldName = "UDF_NICKNAME$";

udfField.Value = "JOEY";

salesOrder.OtherFields.Add(udfField);

Sage eBusiness Web Services Configuration Utility

Use the Sage 100 eBusiness Web Services configuration utility to further define your settings for eBusiness Web Services.

Click Advanced on the Sage 100 eBusiness Web Services window to access eBusiness Web Services - Advanced Settings. Use the advanced settings in this window to modify settings for specific entry points and entities.

Fields can be blocked by clearing the Allow Read or Allow Write check boxes.

Fields can be exposed by explicitly defining them on the Additional Fields tab. When fields are explicitly defined, the fields will appear at the bottom of the grid on the Field Blocking tab where they can also be explicitly blocked.

Any field that exists in Sage 100 for an entity can be defined on the Additional Fields tab. The field does not have to be a UDF.

Manage Entry Points

Entry points can be created and removed from eBusiness Web Services - Manage Entry Points.

Entry points are typically used to hold application specific settings. For example, two clients may be used with eBusiness Web Services. One client can allow the XML for zero values and empty strings to be omitted, while the other client can require the XML to be emitted. Both clients can be served by the same installation of eBusiness Web Services by defining two entry points with different settings for EmitEmptyStrings and EmitZeros.

An entry point must be suffixed with .svc and must have a WSDL type specified.

Error Handling

eBusiness Web Services uses SOAP faults to return errors. SOAP faults contain a faultcode element that will be set to an error code and a faultstring that will be set to a descriptive error message. In addition, SOAP faults generated by the eBusiness Web Services component will include a MasFault element in the detail element of the SOAP fault.

Note: eBusiness Web Services does not report warnings from the Sage 100 system.

The MasFault element contains the following items:

ClassName: The name of the class that generated the error. This item can be blank.
MemberName: The name of the method or property that generated the error. This item can be blank.
ErrorMessage: The error message. This item is always set.

The faultstring element will usually contain a more descriptive message than ErrorMessage as faultstring contains additional detail from the eBusiness Web Services component, while ErrorMessage is typically an error message directly from the Sage 100 system.
ErrorCode: The error code. This item is always set. Both ErrorCode and faultcode will contain the same error code.

Most languages handle SOAP faults through the use of try/catch blocks.

For examples of how to catch eBusiness Web Services SOAP faults for some popular development environments, Quick Start.

eBusiness Web Services-Specific Errors

The following error codes are specific to eBusiness Web Services:

WS_AlreadyExists: "Record already exists."

This error occurs when a create method is called and the record being created already exists. This error can generally be ignored if it is received while retrying a timed out create request as it indicates that the previous call was successful.

WS_EventLog: "Could not write to Windows event log."

All eBusiness Web Services errors are written to the server's Windows Event Log. This error occurs when eBusiness Web Services is unable to write to the Windows Event Log. This is an abnormal condition that may be caused by a permissions or installation issue.

WS_Exception: "An exception occurred."

This error occurs when an unexpected exception occurs while executing an eBusiness Web Services method. The exception detail is not returned by eBusiness Web Services for security reasons. The exception detail can be viewed in the Windows Event Log on the server hosting eBusiness Web Services.

WS_FieldMissing: "The {Business Object} field {Field Name} does not exist in this record."

This error occurs when the record contained in the Sage 100 system does not contain the same schema as defined in eBusiness Web Services. This error will occur when an invalid additional field is defined using the Sage 100 eBusiness Web Services configuration utility. The error may also occur when data is corrupted in the Sage 100 system.

WS_FieldNotAllowed: "Field does not exist or is blocked."

This error occurs when a blocked field is written to or when a field does not exist.

WS_HaveSession: "Session already exists."

This is an eBusiness Web Services internal error and represents an abnormal condition. Report the error to Sage 100 Customer Support.

WS_NullValue: "Value is null."

This error occurs when a required value, such as a key value, is not set.

WS_Unknown: "Unknown error."

This error occurs when eBusiness Web Services is unable to obtain an error code from the Sage 100 system. This error represents an abnormal condition. Report the error to Sage 100 Customer Support.

WS_PreAuthFailed: "Could not pre-authorize credit card."

This error occurs when the PreAuthorizeCreditCard operation fails.

Common Errors Not Specific to eBusiness Web Services

The following are common error codes that are not specific to eBusiness Web Services

CI_NoKey: "Record does not exist."

This error occurs when the record for a get or update operation does not exist.

SY_InvalidPassword

"The user logon or password does not match or the user logon is not enabled for web services."
"Blank passwords cannot be used with web services."

This error occurs when the logon credentials for the Sage 100 system are incorrect. This error will occur when the user name does not exist, the password is incorrect, or the user name is not enabled for web services.

SY_NoAccess: "You are not authorized to perform this action."

This error occurs when the logon does not have proper rights in the Sage 100 system role security to perform an operation. For information on the rights required to perform an operation, see APIs.

This error may also occur when either the Sage 100 system or company is not enabled for web services. When this occurs, the SOAP faultstring will be:

"Web services are not enabled for the system."
"Web services are not enabled for this company."

The ErrorMessage under MasFault will remain "You are not authorized to perform this action."

SY_UserLocked: "This user account has been locked. See your system administrator."

This error occurs when the user account has the locked flag set in the Sage 100 system.

Quick Start

This section is designed to get you started with eBusiness Web Services quickly and easily. This section assumes that eBusiness Web Services has been installed with the default settings.

The following code examples are available on the Sage 100 installation program in the Documents\eBusiness Web Services Examples folder.

Visual Studio 2013 or 2008 (Other than Smart Device Projects)

Create a new project.
From the menu, choose Project/Add Service Reference.
At the Address field, enter: https://<servername>/ebusinesswebservices/masservice.svc?wsdl
Click Go. MasService will appear in the Services section.
Type masws in the Namespace field.
Click Advanced.
Select System.ComponentModel.BindingList in the Collection type field.
Click OK to close the Service Reference Settings window.
Click OK to close the Add Service Reference window.

Your project is now set up to use eBusiness Web Services.

C# Example

// An example of how to create a sales order using ABC demo data

public void CreateSalesOrder()

{

// Create a sales order object

masws.SalesOrder salesOrder = new masws.SalesOrder();

// Create the lines collection for the sales order

salesOrder.Lines = new BindingList<masws.SalesOrderLine>();

// Set the customer information for the sales order

salesOrder.ARDivisionNo = "01";

salesOrder.CustomerNo = "ABF";

// Create a sales order line object

masws.SalesOrderLine salesOrderLine = new masws.SalesOrderLine();

// Set the line information

salesOrderLine.ItemCode = "1001-HON-H252";

salesOrderLine.QuantityOrdered = 1;

// Add the line to the sales order

salesOrder.Lines.Add(salesOrderLine);

// Create a logon object

masws.Logon logon = new masws.Logon();

// Set the username and password to be used for Sage 100 Web Services

logon.Username = "webservices";

logon.Password = "password";

// Create a string with the company code to use

string companyCode = "ABC";

// Use try/catch blocks to catch any errors

try

{

// Create a client to communicate with Sage 100 Web Services

masws.MasServiceClient client = new masws.MasServiceClient();

// Get a new sales order number

salesOrder.SalesOrderNo = client.GetNextSalesOrderNo(logon, companyCode);

// Create the sales order

client.CreateSalesOrder(logon, companyCode, salesOrder);

// Display the order number

MessageBox.Show("Created order# " + salesOrder.SalesOrderNo);

}

// Catch Sage 100 specific faults that occur at the web server

catch (System.ServiceModel.FaultException<masws.MasFault> ex)

{

// Display the error message

MessageBox.Show(ex.Message);

}

// Catch other exceptions (e.g. a connectivity error)

catch (Exception ex)

{

// Display the error message

MessageBox.Show(ex.Message);

}

VB.Net Example

' An example of how to create a sales order using ABC demo data

Sub CreateSalesOrder()

' Create a sales order object

Dim salesOrder As masws.SalesOrder = New masws.SalesOrder

' Create the lines collection for the sales order

salesOrder.Lines = New System.ComponentModel.BindingList(Of masws.SalesOrderLine)

' Set the customer information for the sales order

salesOrder.ARDivisionNo = "01"

salesOrder.CustomerNo = "ABF"

' Create a sales order line object

Dim salesOrderLine As masws.SalesOrderLine = New masws.SalesOrderLine

' Set the line information

salesOrderLine.ItemCode = "1001-HON-H252"

salesOrderLine.QuantityOrdered = 1

' Add the line to the sales order

salesOrder.Lines.Add(salesOrderLine)

' Create a logon object

Dim logon As masws.Logon = New masws.Logon

' Set the username and password to be used for Sage 100 Web Services

logon.Username = "webservices"

logon.Password = "password"

' Create a string with the company code to use

Dim companyCode As String = "ABC"

' Use try/catch blocks to catch any errors

Try

' Create a client to communicate with Sage 100 Web Services

Dim client As masws.MasServiceClient = New masws.MasServiceClient

' Get a new sales order number

salesOrder.SalesOrderNo = client.GetNextSalesOrderNo(logon, companyCode)

' Create the sales order

client.CreateSalesOrder(logon, companyCode, salesOrder)

' Display the order number

MessageBox.Show("Created order# " + salesOrder.SalesOrderNo)

' Catch Sage 100 specific faults that occur at the web server

Catch ex As System.ServiceModel.FaultException(Of masws.MasFault)

' Display the error message

MessageBox.Show(ex.Message)

' Catch other exceptions (e.g. a connectivity error)

Catch ex As Exception

' Display the error message

MessageBox.Show(ex.Message)

End Try

End Sub

Java using NetBeans IDE

Create a new project.
Right click the project and select New/Web Service Client.
In the New Web Service Client page, select the WSDL URL option and enter the following:

https://<servername>/ebusinesswebservices/masbasicwsdl.svc?wsdl
Click Finish.

Your project is now set up to use eBusiness Web Services.

Java Example

// An example of how to create a sales order using ABC demo data

public void CreateSalesOrder()

{

// Create a sales order object

com.sage.mas90.ws.SalesOrder salesOrder = new com.sage.mas90.ws.SalesOrder();

// Create the lines collection

salesOrder.setLines(new com.sage.mas90.ws.ArrayOfSalesOrderLine());

// Set the customer information for the sales order

salesOrder.setARDivisionNo("01");

salesOrder.setCustomerNo("ABF");

// Create a sales order line object

com.sage.mas90.ws.SalesOrderLine salesOrderLine = new com.sage.mas90.ws.SalesOrderLine();

// Set the line information

salesOrderLine.setItemCode("1001-HON-H252");

salesOrderLine.setQuantityOrdered(1.0);

// Add the line to the lines collection then attach the lines to the sales order

salesOrder.getLines().getSalesOrderLine().add(salesOrderLine);

// Create a logon object

com.sage.mas90.ws.Logon logon = new com.sage.mas90.ws.Logon();

// Set the username and password to be used for Sage 100 Web Services

logon.setUsername("webservices");

logon.setPassword("password");

// Create a string with the company code to use

String companyCode = "ABC";

// Use try/catch blocks to catch any errors

try

{

// Create a client to communicate with Sage 100 Web Services

com.sage.mas90.ws.MasBasicWsdlService service = new com.sage.mas90.ws.MasBasicWsdlService();

com.sage.mas90.ws.IMasService client = service.getBasicHttpBindingIMasService();

// Get a new sales order number

salesOrder.setSalesOrderNo(client.getNextSalesOrderNo(logon, companyCode));

// Create the sales order

client.createSalesOrder(logon, companyCode, salesOrder);

// Display the order number

JOptionPane.showMessageDialog(null, "Created order# " + salesOrder.getSalesOrderNo());

}

// Catch Sage 100 specific faults that occur at the web server

catch (com.sage.mas90.ws.IMasServiceGetNextSalesOrderNoMasFaultFaultMessage ex)

{

// Display the error message

JOptionPane.showMessageDialog(null, ex.getMessage());

}

// Catch Sage 100 specific faults that occur at the web server

catch (com.sage.mas90.ws.IMasServiceCreateSalesOrderMasFaultFaultMessage ex)

{

// Display the error message

JOptionPane.showMessageDialog(null, ex.getMessage());

}

// Catch other exceptions (e.g. a connectivity error)

catch (Exception ex)

{

// Display the error message

JOptionPane.showMessageDialog(null, ex.getMessage());

}

PHP 5

PHP 5 is a loosely typed scripting language that does not generate proxies for its SOAP client. There is no setup procedure required to use eBusiness Web Services with PHP.

PHP 5 Example

function CreateSalesOrder()

{

// Set the customer information for the sales order

$salesOrder->ARDivisionNo = "01";

$salesOrder->CustomerNo = "ABF";

// Set the line information

$salesOrder->Lines[0]->ItemCode = "1001-HON-H252";

$salesOrder->Lines[0]->QuantityOrdered = 1;

// Set the username and password to be used for Sage 100 Web Services

$logon->Username = "webservices";

$logon->Password = "password";

// Create a string with the company code to use

$companyCode = "ABC";

// Use try/catch blocks to catch any errors

try

{

// Create a client to communicate with Sage 100 Web Services

$client = new SoapClient("https://server/ebusinesswebservices/masbasicwsdl.svc?wsdl");

// Get a new sales order number

$response = $client->GetNextSalesOrderNo(array(

"logon"=>$logon,

"companyCode"=>$companyCode)

);

$salesOrder->SalesOrderNo = $response->GetNextSalesOrderNoResult;

// Create the sales order

$client->CreateSalesOrder(array(

"logon"=>$logon,

"companyCode"=>$companyCode,

"salesOrder"=>$salesOrder)

);

// Display the order number

echo "Created order# $salesOrder->SalesOrderNo";

}

// Catch all exceptions

catch (Exception $ex)

{

// Display error message

echo $ex->getMessage();

}