The current implementation of Sage100 (C5+) uses gRPC calls to a satellite web service on the client's local Sage100 machine to integrate with Sage100.
- Technology: Azure
- Sphere: Documentation
- SDLC: Environment
- Cadence: N/A
¶ Documentation
Sage 100 Documentation Link Sage 100 Help & File Layouts (2022)
Prior versions (years):
¶ Server Agent – A Note to Clients
Sage 100 does not have an open API endpoint, which means the connector must be hosted on the same network as Sage 100. The Sage 100 connector has been built to work as a separate software that can be installed on the same server as Sage 100. The Server Agent is very lightweight and creates an Open API that the rest of Clarity Connect is able to connect with over the internet. We will need approval from the client/vendor hosting Sage 100 to install the Server Agent. Once installed, the agent will need to have the ability to call out to Clarity Connect. Creating firewall rules and a site-to-site VPN are possible methods to provide that access. Further elaboration can be had with the help of a Connect team member.
¶ Key Terminology
- Customers: Sage treats Accounts as Customers
- Products: Sage considers all Products to be Items
¶ Known Integrations
¶ IDS (Connect v4.7)
- Developers: (P) Jim Lynch
- Integrations: Accounts (To/From), Items (From), Sales Orders (To/From),
- Current Branches:
4.7/develop
¶ CARE (Connect v3)
- Developers: (P) Anonymous User
- Integrations: Accounts (To/From), Sales Orders (To/From), Invoices (To/From), Items To/From)
- Current Branches:
support/clients/care/dev/PushToProduction
¶ GQM (Connect v3)
- Developers (P): Anonymous User, (A): Isaiah Standridge
- Integrations: Purchase Orders (To/From), Items (To/From), Sales Orders (To/From), Sales Order History (To/From)
- Current Branches:
support/clients/gqm/feature/96808-AddsSalesOrderDeletesFunction
¶
¶ Authentication
¶ Connect → Satellite
- Requires the IP address of the machine the Satellite is installed on as well as the port the satellite is using. This will go into the Saved Args in Connect as SatelliteIP (ex. "http://localhost") and SatellitePort (ex. 2663)
¶ Satellite → Sage100
- The Satellite web project (https://dev.azure.com/clarity-ventures/Connect/_git/C4.Modules.ESM.Sage100?path=/Satellite.Modules.Sage100) has an appSettings.json file with the key "Sage100AgentOptions" and the following fields:
{ "Sage100AgentOptions": { "Path": "C:\\Sage 100\\v2018\\MAS90\\", "Username": "User", "Password": "p@$5", "Company": "ABC", "IsDebug": true } }- Path: Path to the MAS database
(ex. "C:\\Sage 100\\v2018\\MAS90\\")- NOTE: This needs to be a path to the server's MAS90 directory. Utilize a UNC path if necessary
(ex. "\\\\SageServer\\Sage\\MAS90").
- NOTE: This needs to be a path to the server's MAS90 directory. Utilize a UNC path if necessary
- Username: Username to access the Sage 100 data
- Password: Password to access the Sage 100 data
- Company: The company code that matches the company in Sage 100 (ex. "ABC")
- "IsDebug": Boolean value you can set to view debug message in the Satellite terminal view. (ex. true)
- Path: Path to the MAS database
¶
¶ CRUD Operations
¶ CREATE
- The field name on the entity must match the field names on Sage
- Sage 100 has internal methods that it uses to interact with Sage objects
This Link contains refrences to some of these methods
Key Property
- The first thing that needs to be written is the key
- The key to that object is specific to the business object
- Some objects only have 1 key
- Some objects may have 2 keys
In the satellite create request you must include the GetKeyName
This is usually “nGet{keyname}”
In the integration service you must invoke the GetNextKey method followed by a SetKey method
Properties
- This method already exists in the integration service
- It will iterate through properties in order
- Order does matter because some properties need to be set first
- See default descending
- We use the SetValue method property to set the values of the property
a) Write method to write property
b) The write method writes lines to an object
¶ READ
- Properties are pulled from Sage using the Default Desc
- Open a Customer entity
- Then Scroll to the bottom to see the DefaultDesc
- These fields are numbered to ensure that we include all the fields
- Here are all the properties for our customer objects
- a. Found Here
- These numbers will be used for mapping these properties with auto mapper
- Navigate to your CustomerProfile
- Note the array index matches the DefaultDesc numbering
- Note that the integers and decimals are retrieved slightly differently than string values
- Go back to the item entity and scroll down to STR(NumberOfInvToUseInCalc)
- Note the property is proceeded by an
STR, the property is in parentheses, and no ”$” after the property name - Back in the CustiomerProfile class ensure that these properties are using the (ToNullableInt) or (ToNullableDecimal) methods
¶ Connect Specifics
¶ Create Job for Sage 100
1. Create the method that you need with a descriptive title in the job itself
[This is in the Connect Job]
Note: Ensure that the method does not already exist in the Sage100Service file
[This is in the Integration]
2. In Sage100Service create the method that will call the Sage100AgentService method that you will create next.
[This in the Integration Service]
Note: Follow the pattern of similar methods in the files. For example, if you need a create method, find another create method and follow its pattern.
3. In the Sage100AgentService (Place the method in the corresponding partial class) create your new method.
4. Following the pattern, create your new method that will Read, Create, or List the data that you need.
5. Use the list request object to create the appropriate object to pass to the list request. This same pattern is followed for all other methods as well. If you have a create request, it will be a new CreateRequest. The Module Name, Program Name, Business Object name and the Key Column can be found in the Sage 100 NFR on 10.100.70.2.
The Corresponding partial class should exist as most Entities are being used. If the partial class, for a new Entity does not exist, please create a new partial class.
Note: You may also use the search bar to search for the particular entity for which you need to create a request. This will give you the business object itself, its properties, and its methods.
6. Update the partial interface at the bottom of the partial class with the new method.
Note: Any parameters in the Sage100AgentService must be JSONWrapped due to the constraints of the satellite.
¶ Sage 100 Workflows
¶ Client Project
1. This is where your different connect jobs are created
a. Your jobs will call Sage 100 connector
¶ Sage 100 Connector
public async Task<Customer[]> ListCustomers(
DateTime? compareDate,
DateTime? maxCompareDate,
CancellationToken token)
{
try
{
var response = await _service.ListCustomers(
compareDate,
maxCompareDate,
token).ConfigureAwait(false);
var retVal = ThrowIfFailedOrReturnResult(response);
return retVal;
}
catch (Exception ex)
{
var test = ex.Message;
throw;
}
}
1. This is an example of a service calling the Sage 100 Satellite
a. This is calling the satellite not the integrations service
b. The Primary difference that includes a “ThrowIfFailedOrReturnResult(response)” Method
¶ Sage 100 Satellite/Agent Service
public async Task<SatelliteResponse<Customer[]>> ListCustomers(
JSONWrapped<DateTime?> compareDate,
JSONWrapped<DateTime?> maxCompareDate,
JSONWrapped<CancellationToken> token)
{
try
{
ListRequestObject listRequestObject = new ListRequestObject
{
CompareDate = compareDate,
MaxDateToCompare = maxCompareDate,
ModuleName = "A/R",
ProgramName = "AR_Customer_ui",
BusObjName = "AR_Customer_bus",
KeyColumn = "ARDivisionNo$+CustomerNo$",
DescColumn = Customer.DefaultDesc,
DefaultDescColumn = Record.DefaultDesc,
Filter = "",
Begin = "",
End = "",
};
var request = new CustomerListRequest<Customer>(listRequestObject);
var result = await _service
.List<Customer, CustomerListRequest<Customer>>(request);
return SatelliteResponseExt.SuccessResponse(result);
}
catch (Exception ex)
{
return SatelliteResponseExt.FailedResponse<Customer[]>(ex.Message, ex);
throw;
}
}
- This is the actual call to the Sage 100 integration service
- The parameters need to be json wrapped
¶ Known Customizations
- Products (To)
- Flagging
- Diff Key Caching
- Sales Orders (From)
- Orders API V3 Meta Fields
- Sales Orders (To)
- Changed Sales Orders
- Sales Orders (Deals)
- Sales Order Account Creation
- Invoices (Deals)
- Sync Restriction: On Fulfilment
- Memos Sync
- Sales Orders
- Deleted SOs
- Purchase Orders
- Deleted POs
- BOLs
- BOM Production Entries
- Inventory Receipts
¶ Outlying Issues
¶ Casting Errors
-
If any object in the call is abstract you will not be able to cast to the Record
-
It can be from the entity or the mapping profile
(Rare) If the object you are using isn’t abstract you could be using the incorrect object with the same number of properties that will throw a casting error due to a type mismatch
The properties are mapped in an array are matched using the default descending
Default descending on the entity
This is the mapper profile of the entity
- If you are working on this as a satellite you can’t use any breakpoints
- Essentially you must log progress into a console log
- Another part of this being a Satellite is any time you make changes to the satellite project you must redeploy the satellite(Republish first)
- You need to be sure your services are actually running
- You can’t host multiple developers on the satellite
- The satellite doesn’t automatically close when you stop running visual studio
- You will need to manually close the satellite
In the module name/program name/business object name, one of those is incorrect or some combination
Make sure they are correct in your request object
¶ Common Model Mappings
¶ Common Model Workflows
Phase 2