Pub/Sub API Accounting Integration

The Pub/Sub Accounting Integration allows any system capable of accessing the Salesforce Pub/Sub API to seamlessly integrate accounting with the TMS. The TMS sends outbound accounting events (Customer, Vendor, Load, Customer Invoice, and Vendor Invoice) to the Pub/Sub API event bus for processing by the accounting system. The TMS is also able to process inbound accounting events (Customer Payment and Vendor Payment) sent to the Event Bus by the accounting system.  

The main Salesforce components used by this integration include a Connected App for authentication purposes, Platform Events, and the Pub/Sub API.

Setup Connected App Access

A connected app is required to allow the accounting system to access the Pub/Sub API. Through the connected app there are several OAuth authorization flows supported by Salesforce. The setup below outlines the setup of an OAuth 2.0 Client Credentials Flow connected app. Other flows are also supported.

Three fields must be sent to the accounting partner to complete the Pub/Sub setup process. Each are referenced in the steps below. They are the Consumer Key, Consumer Secret, and Current My Domain URL fields.

Step 1: Create a new API user

Create a new user:

1. Navigate to Setup and then search for and click the Users link.

2. Click the New User button and add the following:

   • First Name: Accounting

   • Last Name: Integration

   • Email: Set to the system admin’s email.

   • Username: Change if necessary.

   • User License: Salesforce

   • Profile: Standard User

Note: The user’s First Name and Last Name can be any value, but should reference accounting for simplicity.

3. Click Save.

4. Add the Permission Set TMS Accounting Integration to the user.

Step 2: Create the Connected App

Skip these steps when the Accounting Integration App already exists.

1. Navigate to Setup and then search for and click the OAuth and OpenID Connect Settings link.

   1. Enable Allow Authorization Code and Credentials Flows.
      
      

2. Create a Connected app by following the steps below.

   1. Navigate to Setup and search for External Client Apps and select the Settings link.

   2. From the Connected Apps section, choose On for Allow creation of connected apps.

      1. Click the Enable button on the modal to create Connected Apps.

   3. Click the New Connected App button.

      

3. Enter the following information:

   1. Connected App Name: Accounting Integration

   2. API Name: Auto-Generated based on the Connected App Name.

   3. Contact Email: System admin’s email.

   4. Enabled OAuth Setting: Checked.

   5. Callback URL: https://login.salesforce.com/.

   6. Selected OAuth Scopes: Add Manage user data via APIs (api)

   7. Enable Client Credentials Flow: Checked.

   8. Click Save.

      

Step 3: Setup the Connected App

1. Navigate to Setup and then search for and click the App Manager link.

2. In the Accounting Integration app row click the arrow and select to View.
   

3. Go to Trusted IP Range for OAuth Web Server Flow and add any applicable IPs (optional).

4. Click Manage Consumer Details to access the Consumer Key and Consumer Secret which are required for the accounting system.

   The Consumer Key and Consumer Secret are provided by the accounting partner.

   

   

Step 4: Setup Client Credentials Flow

1. Navigate to Setup and then search for and click the App Manager link.

2. In the Accounting Integration app row click the arrow and select to View.

3. Click Manage at the top of the page.

   

4. Click Edit Policies.

5. Under Client Credentials Flow Set Run As to the new user that was created (Accounting Integration).

   

6. Click Save.

7. The following endpoint must be provided to the accounting system. “{domain}” is found by navigating to Setup, search for My Domain and click the link. Copy the link from Current My Domain URL into the URL below.

   1. OAuth authorization endpoint: https://{domain}/services/oauth2/token

      The Current My Domain URL field must be sent to the accounting partner to complete setup.

Accounting System Access to the Pub/Sub API

Salesforce documentation should be consulted for details on accessing the Pub/Sub API with the accounting system. The accounting system requires the URL created above with the Consumer Key and Consumer Secret.

Salesforce Pub/Sub API Documentation

Publishing and Subscribing to the Event Bus

Each time a payload is published or a subscribed payload is received is called an "Event." Each event has a unique field, the EventUUID. If there is an Event failure, a Queued Transaction is created with the EventUUID and the system administrator is notified.

Inbound Events

The TMS "listens" for subscribed events from the Event Bus. When subscribed events occur, the records are added to the TMS. The two events the TMS listens for are published Customer Payments and Vendor Payments.

Subscribing events call the streamFetchRequest API and receive a streamFetchResponse in return.

Customer Payment

When a cash application is posted to a Customer Invoice in the accounting system, a payload is published to the Event Bus. The TMS is subscribed to these events and accepts the payload.

The following fields for a Customer Payment record are created and populated from the Event Bus.

{
	"paymentId": "22s8dje8dje9dke9ew",
	"paymentType": "Check",
	"checkReferenceNumber": "12345",
	"invoiceId": "1js8dje8dje9dke9ew",
	"invoiceNumber": “L-1919293”,
	"paymentDate": “2023-01-23”,
	"paymentAmount": 1000.00,
	"discount": 100.00,
	"paymentCurrency": "USD",
    "customFields":
	[
		{
			"fieldname": "Custom_Field__c",
			"value": "customValue"
		}
	]	
}

Additional fields may be added to the Customer Payment TMS1 Field Set and set by inbound Customer Payment events.

Vendor Payment

Payloads are published when a cash application is posted to a Vendor Invoice in the accounting system. The TMS is subscribed to these events and accepts the payload.

The following fields for a Vendor Payment record are created and populated from the Event Bus.

{
	"paymentId": "33s8dje8dje9dke9ew",
	"paymentType": "Check",
	"checkReferenceNumber": "12345",
	"invoiceId": "1js8dje8dje9dke9ew",
	"invoiceNumber": "L-1919293",
	"paymentDate": "2023-01-23"
	"paymentAmount": 1000.00,
	"discount": 100.00,
	"paymentCurrency": "USD",
    "customFields":
	[
		{
			"fieldname": "Custom_Field__c",
			"value": "customValue"
		}
	]	
}

Additional fields may be added to the Vendor Payment TMS1 Field Set and set by inbound Vendor Payment events.

Outbound Events

The TMS publishes events to the Event Bus. When publish events occur, the records are sent to the Event Bus and are then received by the accounting integration. There are five events the TMS publishes for the accounting system. They include Customer, Customer Invoice, Vendor, Vendor Invoice, and Load event payloads.

The TMS uses Platform Events when publishing to the Event Bus for lightweight and near real time sending of data.

Most outbound payloads include the Salesforce Record ID of the record that is sent as a payload field. See Salesforce for more information on locating the record ID.

Prepare to send accounting information from the TMS by setting the Accounting Status picklist field to Ready for Accounting. The Accounting Status field is a managed Global Picklist Value Set and should not be changed. After a successful publish event, the Accounting Status changes to Sent to Accounting. A status of Publish Error displays if there is an issue and an email is sent to the system administrator.

Several field sets trigger publishing events when values are changed. Add fields to these field sets to send updated information to the accounting integration.

Publishing events call the PublishRequest API and receive a PublishResponse in return.

Customer Payload

The following fields for an Account (Customer) record are published to the Event Bus for the accounting integration.

{
	"customerId": "1js8dje8dje9dke9eq",
	"customerName": "ABC Company",
	"dbaName": "ABC Company",
	"tmsType": "Customer",
	"defaultCustomerBillToId": "aus8dje8dje9dke9ew",
	"defaultCustomerBillToName": "ABC Company",
	"billingStreet": "2333 Waukegan Road",
	"billingCity": "Bannockburn",
	"billingState": "IL",
	"billingPostalCode": "60015",
	"billingCountry": "US",
	"shippingStreet": "2333 Waukegan Road",
	"shippingCity": "Bannockburn",
	"shippingState": "IL",
	"shippingPostalCode": "60015",
	"shippingCountry": "US",
	"customerCurrency": "USD",
	"contacts":
	[
		{
			"contactId": "1d8dkj38djk39dk39d",
			"firstName": "George",
			"lastName": "Smiley",
			"email": "gsmiley@revenova.com",
			"phone": "312-333-9999",
			"role": "Billing"
		}
	]
	"customFields":
	[
		{
			"fieldname": "Custom_Field__c",
			"value": "customValue"
		}
	]	
}

Vendor Payload

The following fields for an Account (Vendor) record are published to the Event Bus for the accounting integration.

Contacts Payload

The following fields for a Contact record are published to the Event Bus as part of Customer and Vendor payloads. Multiple Contact records may be added to a single Customer or Vendor payload.

Load Payload

The following fields for a Load record are published to the Event Bus for the accounting integration.

{
	"loadId": "1js8dje8dje9dke9et",
	"loadName": "Load-12345",
	"customerId": "1js8dje8dje9dke9eq",
	"customerName": "ABC Company",
	"customerBillToId": "1js8dje8dje9dke9eq",
	"customerBillToName": "ABC Company",
	"customerSalesRepId": "1je8dje8e6ehe9eie8",
	"customerSalesRepName": "George Smiley",
	"carrierSalesRepId": "1je8dje8e6ehe9eie8",
	"carrierSalesRepName": "Roy Bland",
	"mode": "Truckload",
	"weight": 20000,
	"weightUnits": "lbs",
	"stops": 
	[
		{
    "stopId": "2j8fj3d9dkj3d9dk303",
			"stopName": "Stop 1",
			"stopNumber": 1,
			"isPickup": true,
			"isDelivery": false,
			"expectedDate": "2023-01-22",
			"appointmentTime": "10:00",
			"locationName": "ABC Warehouse",
			"street": "123 North Ave.",
			"city": "Chicago",
			"state": "IL",
			"postalCode": "60603",
			"country": "US"
		},
		{
     "stopId": "2j8fj3d9dkj3d9dk223",
			"stopName": "Stop 2",
			"stopNumber": 2,
			"isPickup": false,
			"isDelivery": true,
			"expectedDate": "2023-01-22",
			"appointmentTime": "10:00"
			"locationName": "DEF Warehouse",
			"street": "333 North Ave.",
			"city": "Chicago",
			"state": "IL",
			"postalCode": "60603",
			"country": "US"
		}
	],
	"customFields":
	[
		{
			"fieldname": "Custom_Field__c",
			"value": "customValue"
		}
	]	
}

Stops Payload

The following fields for a Stop record are published to the Event Bus as part of a single Load Payload. Multiple Stop records may be added to a Load payload.

Customer Invoice Payload

The following fields for a Customer Invoice record are published to the Event Bus for the accounting integration.

{
	"invoiceId": "1js8dje8dje9dke9ew",
	"invoiceNumber": "L-1919293",
	"invoiceType": "Invoice",
	"customerId": "aus8dje8dje9dke9ew",
	"customerBillToId": "aus8dje8dje9dke9ew",
	"loadId": "s823js8ew888fk39dk",
	"loadNumber": "Load-123",
	"invoiceDate": "2023-01-23",
	"invoiceDueDate": "2023-02-23"
	"invoiceTotal": 2222.50,
	"paymentDiscount": 0.00,
	"taxAmount": 0.00,
	"invoiceCurrency": "USD",
	"charges":
	[
		{
			"chargeType": "Freight",
			"description": "Freight",
			"unit": "Per Mile",
			"unitQuantity": 1000,
			"unitPrice": 1.00,
			"chargeAmount": 1000.00,
    "customFields":
	[
		{
			"fieldname": "Custom_Field__c",
			"value": "customValue"
		}
	]	
		},
		{
			"chargeType": "Fuel",
			"description": "Fuel",
			"unit": "Per Mile",
			"unitQuantity": 1000,
			"unitPrice": 1.00,
			"chargeAmount": 1000.00,
    "customFields":
	[
		{
			"fieldname": "Custom_Field__c",
			"value": "customValue"
		}
	]	
		},
		{
			"chargeType": "Accessorial",
			"description": "Lift Gate Pickup",
			"accessorialId": "q2d4s8ewh37su28sj3",
			"unit": "Per Mile",
			"unitQuantity": 1000,
			"unitPrice": 0.10,
			"chargeAmount": 100.00,
    "customFields":
	[
		{
			"fieldname": "Custom_Field__c",
			"value": "customValue"
		}
	]	
		}
	]
	"customFields":
	[
		{
			"fieldname": "Custom_Field__c",
			"value": "customValue"
		}
	]	
}

Vendor Invoice Payload

The following fields for a Vendor Invoice record are published to the Event Bus for the accounting integration.

{
	"invoiceId": "1js8dje8dje9dke9ew",
	"invoiceNumber": "L-1919293",
	"invoiceType": "Invoice",
	"vendorId": "aus8dje8dje9dke9ew",
	"vendorRemitToId": "1kmd8dk30d3ll30dd",
	"loadId": "s823js8ew888fk39dk",
	"loadNumber": "Load-123",
	"nvoiceDate": "2023-01-23",
	"invoiceDueDate": "2023-02-23"
	"invoiceTotal": 100.50,
	"paymentDiscount": 0.00,
	"invoiceCurrency": "USD",
	"charges":
	[
		{
			"chargeType": "Freight",
			"description": "Freight",
			"unit": "Per Mile",
			"unitQuantity": 1000,
			"unitPrice": 1.00,
			"chargeAmount": 1000.00,
    "customFields":
	[
		{
			"fieldname": "Custom_Field__c",
			"value": "customValue"
		}
	]	
		},
		{
			"chargeType": "Fuel",
			"description": "Fuel",
			"unit": "Per Mile",
			"unitQuantity": 1000,
			"unitPrice": 1.00,
			"chargeAmount": 1000.00,
    "customFields":
	[
		{
			"fieldname": "Custom_Field__c",
			"value": "customValue"
		}
	]	
		},
		{
			"chargeType": "Accessorial",
			"description": "Lift Gate Pickup",
			"accessorialId": "q2d4s8ewh37su28sj3",
			"unit": "Per Mile",
			"unitQuantity": 1000,
			"unitPrice": 0.10,
			"chargeAmount": 100.00,
    "customFields":
	[
		{
			"fieldname": "Custom_Field__c",
			"value": "customValue"
		}
	]	
		}
	]
    "customFields":
	[
		{
            "fieldname": "Custom_Field__c",
			"value": "customValue"
		}
	]	
}

Charge Payloads

The following fields for a Charge record are published to the Event Bus as part of Customer and Vendor Invoice payloads. Multiple Charge records may be added to a single Customer or Vendor invoice from the respective objects.

Freight & Fuel Accessorial Charge Fields