Skip to main content

Tracking Applied Data in AgSync

When information is being exported from AgSync there are a few different methodologies. If using webhooks alone, one can convert data to another without requiring any user interaction with AgSync to authenticate with AgSync.

Authenticating to retrieve work orders will add time to development because it will require addition of a screen which allows the user to authenticate with AgSync and retrieve back authentication information, before making the desired API calls.

However this is usually the next step in the integration.

Diagram demonstrating interaction between ERP and AgSync
Click anywhere to close.
Diagram demonstrating interaction between ERP and AgSync
Click image to expand.

Consuming a Webhook​

Documentation for webhooks is located in this section.

Below, more information is included about consuming work order information. The flow below is based upon retrieving actual amounts for completion. Retrieving amounts which are ready for applications calculated by multiplying the product times the rate.

The other primary difference is if one wanted to receive blended amounts, only import WorkOrder data which is of Scheduled status( ID = 8). The Scheduled status in AgSync reflects when an order has been assigned for applicator and is ready to be sent to the blender.

The user in AgSync would then enter the webhook endpoint. The endpoint is configurable per account, see Branch Location Cross Reference below for more information.

A server and port open is needed when listening for the incoming messages. Raven cannot give out a list of IP addresses because the service used for sending out webhooks may change IP address dynamically. In order to handle this scenario some clients will have a server accept the incoming webhook, then relay it to their customer’s server which ultimately processes the information.

Then they consume the message and convert it to an appropriate format and then import. An error log for orders that did not import due to a missing product or customer cross reference must be present to handle scenarios where the user had entered an incorrect cross reference ID.

Typically failed cross references then notify a user through email or other means stating that there is an order which did not get entered. Some systems then allow the user to correct the information and attempt to re-import, others require a manual entry.

Completion APIs​

In certain instances where there are restrictions set in place not allowing for incoming connections or for those whom do not want to create a server to listen to, AgSync offers several APIs which allow for completed work order information to be retrieved.

One methodology includes calling the GET https://orders.agsync.com/api/orders/completed endpoint periodically to retrieve the list of work orders whom have been completed by using the last modified parameter. Once the list of work orders is retrieved from the API, then an API call to retrieve individual work order information can be performed by GET https://dispatch.agsync.com/api/order/{orderId}/workorders.

This endpoint will return approximately the same work order data as what is included in a webhook. Only one work order is returned in the endpoint.

Work Order Information​

The following section includes detailed descriptions of elements of the work order which is used for cross referencing to the system, verifying that a work order is complete, and calculating how much product and area was applied for a given work order.

Cross Reference​

A specific cross reference ID known as the integrationPartnerId can be created by AgSync to denote the ID is a personal or client one.

Branch Location Cross Reference​

AgSync Branch locations are referred to as an Account in many AgSync APIs. Accounts then are used as the Requester, Service Provider and Suppliers.

AgSync allows a user to enter a Partner branch ID for cross reference into the user interface for an Account. Then an API call can be performed to the Account to GET https://fields.agsync.com/api/accounts to retrieve cross reference information the user has entered.

  • The Branch location entering the order is listed as the Requester.
  • The Branch location who dispatched the order is listed as the ServiceProvider. This could be an outside party that is not even a branch within the system. Typically this occurs when a user orders Application or services from a different company outside of the personal organization who also uses AgSync.
  • The Supplier on each product is used in AgSync to designate what branch or location the product was removed from.

Customer Cross Reference​

AgSync allows for the storage of customer IDs from other partner systems. This data can be provided to AgSync via API described at https://fields.agsync.com/swagger/ui/index or the user may have the ability to enter this data via the AgSync user interface by right-clicking on a customer in the customer tree and choosing view or edit profile info.

The term Billing entity is used in several locations within AgSync and billing entities are the same as customers. The difference being that a billing entity is used to define the billing information listed on an order and is defined in a work order by a list of BillingEntities on the products and charges along with a split percentage. Partner information is included in both Customers and Billing Entities.

Product Cross reference​

Product information can be cross referenced to the personal or client product list by end users by entering personal or client product list in the Account Settings > Integrations > External Product list tab.

When entered and mapped to an AgSync product, the user is forced to select from products entered from the personal or client system.

Order Items​

In AgSync, Products are separated from Services within AgSync's product items. Service Items are recorded as Charges on the Order. To determine the items that would need to be invoiced for a completed order from AgSync, do the following:

  • Loop through the list of services [i] and their Mixes.
    • Each product in the mix becomes an item.
    • The PartnerProductId corresponds to a Product Item Code in the personal or client system.
    • If completed, the sum of product used is calculated as the sum of Order.Service[0].Completions.Products.ActualProductUsed where the Order.Service[0].Completions.Products.ProductId is equal to Order.Service[i].mix.ProductId for the partner product ID being chosen. The completions object repeats on each service therefore the first Completion on the first service is often used for calculations.
  • Loop through the list of charges.
    • Each Charge on the Order will become a line item.
    • The ERP product item code for the charge is the Charge.PartnerId.
    • The total acres on a completed work order is shown as the sum of the WorkOrder.Service[0].Completions.Services.CompletedAcres.

AgSync Order ID​

The AgSync order id as it is displayed in AgSync is included as the Order.OrderExtendedData.OrderId and it will be unique for each order. Use this value or the Order.Id to ensure that duplicates are not created within the personal or client system because AgSync will continue to be send webhooks upon any further changes in AgSync.

Coverage Data​

Coverage Data is included in the work order as the AppliedWkt parameter. The data provided in this field is geometry placed in the Well Known Text or WKT format. Data which appears in this may be returned in the Slingshot Connected Workflow or manually uploaded data which may have been from an aerial application. The information included is the same as what a user may see by viewing published Swath data on a use report.

One important consideration is that this data item can become very large (greater than 1-2 MB). If using a queuing system with a limited message size, it is suggested to strip this data out before processing the work order.