Home > Integrations Support > Administrator Guide > D-Tools SI API Overview

D-Tools SI API Overview

Table of contents
  1. Details
  1. Details

 

Details

 

All following information relates to the D-Tools System Integrator (on-premises or hosted server) API. This API is not for D-Tools Cloud, but just for the D-Tools System Integrator.

 

Please take a moment to review our overall API capabilities and considerations. This will help you understand how our API works and will answer most of the preliminary questions you may have. This page is updated when new features become available.

 

The D-Tools SI API is Cloud-based and has been created to bridge the data from the on-premises (or hosted) D-Tools instance to a cloud API Server, where it becomes available for subscription and updates from/to a 3rd party application.

 

It is important to understand how our API has been designed in relationship to our product: As an on-premises application (regardless if the server is installed locally or is hosted), SI has no directly accessible API. Instead, we have created a middle-ware solution running on our cloud, simulating a queue for data. When you POST data to the API, that data is stored on the API until it is applied to D-Tools SI. To consume data from the API, D-Tools SI must first export data to the API. The export of data (i.e. project export) can be done manually or automatically

 

CLOUD API

 

FEATURES AVAILABLE

  • Projects and Change Orders
    • Publish (POST) New SI project and change orders 
    • Update (POST) Existing SI project 
    • Subscribe (GET) SI projects and Change orders
  • Catalog
    • Subscribe (GET) Products
    • Create or Update (POST) Products
  • Tasks
    • Subscribe (GET) Tasks
  • Service Orders 
    • Publish (POST) New Service Orders 
    • Subscribe (GET) Service Orders
  • Purchase Orders
    • Subscribe (GET) Purchase Orders
  • Service Plan
    • Subscribe (GET) Service Plans
  • Time Sheets
    • Subscribe (GET) Time Sheets
  • Clients
    • Publish (POST) New Clients.
    • Update (POST) Existing Clients
    • Subscribe (GET) Clients (will be available in v21 - mid-February release) 
  • Webhooks (will be available in v21 - mid-February release) 

 

Please note that the old Change Order method (before SI2017, and based on revision compare) is deprecated. Please use the Change Order feature in D-Tools and the Projects / Change Orders Subscribe service to retrieve Change Orders data.

 

WEBHOOKS

Our webhooks offer a comprehensive range of features and functionalities, tailored to meet diverse user requirements and preferences:

Authentication Options: Users have the flexibility to choose from various authentication methods:

  • Basic Authentication only (username and password).
  • Headers only (excluding username and password).
  • Both Basic Authentication and Headers.
  • None: Leaving all fields blank.

 

API Key Integration: The inclusion of the API key in the webhook post object enhances both security and integration efficiency.

Webhook Post Object Elements:

  • API Key: Links to the Integration and SI License.
  • Id: The identifier of the object posted, which can be used to retrieve the full object from the API.
  • Type: Options include Create, Update, or Delete (with Delete currently supported only in projects).
  • Module: Various types such as Product, Project, Partial Project, Purchase Order, Service Order, Service Plan, or Time Sheet.
  • UpdatedOn: Records the UTC date and time of the publication.

 

Enhanced Reliability: The webhook code in SI v21 logs both successful and failed attempts. In case of failure, the system executes three retry attempts at intervals of approximately 5, 15, and 30 minutes. After four total attempts, no further attempts are made.

 

Logging and Monitoring: The new Log button in the Manage Webhooks section in SI displays logs of successful and unsuccessful attempts for a selected webhook, including fields like Status, Number/Name, Date, Error, Attempts, and Last Attempted time.

 

Webhooks are incredibly useful for automating reactions to events within a system or application. They function as user-defined HTTP callbacks which are triggered by specific events. When an event occurs, the source site makes an HTTP request to the URL configured for the webhook. This mechanism allows for real-time data transmission, efficient inter-system communication, and immediate response to events.

 

Real-world Example: Imagine a scenario in a sales management system where every time a new sale is recorded, a webhook is triggered. This webhook could be configured to automatically send an HTTP request to a CRM (Customer Relationship Management) system. The request would contain details of the sale (like sale amount, customer information, and product details) encapsulated in the webhook post object. This real-time update would enable the CRM system to immediately log this new sale, update the customer's purchase history, and potentially trigger other processes like inventory adjustment or personalized customer follow-up emails. This automation not only saves time but also ensures that all systems are synchronized with the latest data, improving efficiency and customer experience.

 

Below is an example of a JSON payload for a webhook that incorporates the features described above. This example assumes a scenario where a new sale has been recorded, and the webhook is triggered to update a CRM system:

 

{
  "ApiKey": "my_api_key",
  "Type": "Update",
  "Module": "Project",
  "Ids": [
    "5791e708-4c59-4d8c-9fec-11635bc93679"
  ],
  "UpdatedOn": "2024-02-13T18:28:48.6806156"
}

 

This JSON structure showcases several key elements:

  • APIKey: Unique identifier for the Integration and SI License.
  • Id: Identifier of the sale object.
  • Type: Denotes the action type, here it is a "Create" action.
  • Module: Specifies the module type, in this case, "Sales".
  • UpdatedOn: The UTC timestamp of when the webhook was triggered.
  • Data: Contains detailed information about the sale, including customer and product details.
  • Authentication: Demonstrates the use of Basic Authentication with a username and password.
  • Headers: Includes additional HTTP headers that may be required for the request.

 

IP ADDRESS AND SERVER LOCATION

We call our API (https://api.d-tools.com) on the IP 52.34.10.235.
This server is located n the US, West Oregon data center of AWS.

The SI Client directly calls API endpoint on the AWS server (api.d-tools.com) and it does not go through the SI Server when doing Export to integration.
 

 

AUTOMATION

We offer four settings related to Automation:

 

  • Revision Creation:
    • Automatically Create a Revision on "Update Project".

 

  • Automatic Update (From the API to SI) - The SI Server can automatically pull data from the API and update the SI database for the following services
    • Update Clients
    • Project Creation
    • Change Orders Creation
    • Catalog Products Creation and Updates

 

  • Automatic Update (From SI to the API)
    • Export Catalog (Group of Items) - Can choose the Integration and Price Type
    • Projects - Export Projects based on Specific Project statuses and independent integrations. We have defined three use-cases for the logic involving automation export, as follows:

a.   Always, automatically Export a project with "any statuses" to the default integration upon project check-in. This option will always export the project to the API upon project check-in, regardless of the project status.  This scenario is for companies that are using Project Management Apps, which requires the project to be pushed as they are built/changed/approved/lost, etc... This will give a sense of real-time visibility on third-party integrations.

 

b.   Always, automatically Export a project with "specific status(es)" only, to the default integration upon project check-in. This is similar to the use-case noted above,  where multiple recurring pushes are setup. The difference is that only specific status(es) are selected.

 

c.   Conditionally, automatically Export a project with "specific status(es)" to the default integration upon project check-in. The condition is, if the project status changes, export. If it doesn't change, don't export. As an example, this scenario would be for companies using third-party accounting apps, where they would specify a single status to export to their accounting app, and to only (automatically) push it once.

 

Please go to Start -> Setup -> Contol Panel -> Manage Integrations -> Settings to setup your automation..

 

  • Integration to SI (Import Timer)

The first run is 15 minutes after the SI windows service start (the service will start when the machine starts or it is restarted).

Then every 4 hrs from the first run.

 

  • Catalog Automation (SI to Integration)

The first run is 30 minutes after the SI windows service start (the service will start when the machine starts or it is restarted).

Then every 24 hrs from the first run.

 

 

CONSIDERATIONS

  1. Very Important to understand: Our API works as a "queue" for:
    • Projects and Catalog "list of equipment(s)" that are manually exported to the API. 
    • If exported by D-Tools SI, it becomes available for consumption by a third-party application
    • If exported by a Third-party application, it becomes available for consumption by D-Tools
    • For a Project, 
      • If the project does not exist in D-Tools SI, it becomes available for "New Project from an integration"
      • If the project exists in D-Tools SI, it becomes available for "Update from an integration"
  2. A catalog can contain up to 10000 records.
  3. To access the API, users must be on the latest version of D-Tools. The access with an outdated version is not supported and may not work.
  4. To access the API, users must be enrolled in the Software Assurance (SA) program.
  5. Change Orders. D-Tools can handle change orders from existing D-Tools projects, and export the changes or the updated project to their third-party integration. The integration call works for both projects and change orders. We have an enhanced Change Order function (available on SI2018 or later), and users will likely prefer to Manage Change Orders in SI. Here is a link that explains this function: https://support.d-tools.com/001_SI_2018_Documentation/User_Guide/04_Projects/01_Project_Explorer/07_Change_Orders
  6. Installation Task and Service Orders are not part of our API. Based on the general idea of division/separation of software capabilities, installation and service management is likely a feature to be handled on their third-party integration, so it is not a current concern.
  7. Certain features can be disabled in SI, either by the “privileges” (set on each user group) or by the licensing type. However, since D-Tools SI is an on-premises app, users with a full license have complete control, and privileges are managed by each company.
  8. Ideally, a workflow, similar to the one described below, should be created in collaboration between our teams. This should help guide our customers on how the integration works and what results are expected if they follow this process.
  9. Our integration should revolve around integrating projects and updating the projects back and forth as applicable. Good flexibility is to allow users to be able to add items on both applications (there are good use-cases to advocate those options, and for usability purposes, this should be permitted) but this brings a consolidation concern. A good way to handle this concern is by suggesting users to create or map items only when a project is created in their third-party integration from D-Tools or updated in D-Tools from their third-party integration.
  10. For an initial database matching effort, we would recommend a manual export/import of vendors, clients, and parts; we can use our export/import functionality, available through a CSV file, or bridged through QuickBooks or Outlook. Consecutive pushes/updates should be handled through the project's export and import. We don’t recommend developing code for the initial database creation. There are many variables to how users may want to proceed with this step, and it seems easier to manually perform this initial function.
  11. D-Tools does not handle any accounting operations or inventory capabilities. if using QuickBooks, D-Tools users should consider integrating with QuickBooks through their third-party integration or from D-Tools.
  12. There is an API key associated with each of the license keys. This is required on the calls to the API, as described on the documentation. For information on how to use the API Key, please review the following link: http://support.d-tools.com/API_Support/Administrator_Guide/API_Key
  13. Manage Integrations: For information on how to Manage your integrations, please review the following link: http://support.d-tools.com/API_Support/Administrator_Guide/Manage_Integrations
  14. When a project is exported from D-Tools to their third-party integration, all available information on both the project and itemized project_items is parsed. This includes Project Name, Client Name, Addresses, and for each item, Manufacturer, Model, IP address, Serial Number, Vendor, and many more. For a complete list, please visit:
    1. Project related data: https://api.d-tools.com/SI/doc/ResourceModel?modelName=Project
    2. Project’s items related data: https://api.d-tools.com/SI/doc/ResourceModel?modelName=ProjectItem

 

LABOR ENDPOINTS CONSIDERATIONS

  1. Fixed Labor, We pass the quantity of 1 or quantity of multiple fixed labor if the call aggregates similar items together. Labor Hours are always zero for fixed labor.
  2. Variable (or Calculated) labor: We pass the labor hours in both the labor hours field and the quantity fields (quantity and labor hours are the same for variable labor items)
  3. Phase or Labor Type Labor: It gets aggregated as a “new” labor line item (type 2) where the quantity equals total labor hours.
  4. Equipment: Labor hours are the associated labor hours for that specific product. The Product Phase (if assigned) is also available on “Phase” endpoint.

 

SUGGESTED PATTERN

  1. If the user elects to use the CRM capabilities from their third-party integration, the process will start there
  2. When a user wants to create an SI project from their third-party integration opportunity, they export their third-party integration Opportunity to SI.
  3. In SI, the user selects “New project from an integration”
  4. If not using an initial third-party integration Opportunity then users would create a “New Project” in SI, and the process would start here.
  5. A user manages the project in SI until he/she is ready to send it back to their third-party integration. This is one of the most important abstractions to consider when developing an integration pattern.
  6. The user has an automation scheme enabled, or will click on “Export” to their third-party integration, and the project is sent to our API
  7. Their third-party integration consumes the project data from our API, and ideally, they would have the flexibility to map the SI project to a new or existing opportunity, and creating their third-party integration project/opportunity accordingly. 
  8. If the user wants to manager Change Orders in SI, they can push each Change Order to their third-party integration. For this capability, users may want the flexibility to push each CO to the same or new opportunity. 
  9. If the user makes changes into their third-party integration project and wishes to update the respective D-Tools project with their information, this is also available. We don’t necessarily recommend this process, but it is available. We don’t recommend it because, from a process perspective, one of the two applications should be elected to make changes to the projects. Nonetheless, it is available.

 

Suggested Company Workflow.jpg

 

 

AGGREGATION OF PROJECT ITEMS

Aggregation of Project Items (to display quantity and significantly reduce the size of the call) is available on the "SubscribeProjects (Get a specific project for a given project id published by a SI user) Service. You can group by:

  • Item
  • Location
  • System
  • Phase

 

Please note that the value of the following fields determines the quantity of items grouped together (quantity)

  • TypeId
  • LaborType
  • Manufacturer
  • Model
  • PackageName
  • PartNumber
  • IsOfe
  • IsNonBillable
  • UnitCost
  • UnitPrice
  • LaborHours
  • IsTaxable
  • TaxId
  • Vendor

 

CONSIDERATIONS ON "QUANTITY" OF SIMILAR ITEMS

In D-Tools SI V18, we added two new fields for the project item: “Quantity” and “TotalQuantity”.

  • TotalQuantity = item quantity * parent item quantity * package item quantity * solution item quantity.

 

  • For bulk wire, the quantity is the wire length * total quantity
  • For variable labor items, the quantity is the labor hours * total quantity
  • For other items, the quantity is the total quantity

 

When we import items from the API, if the project_items quantity is based on a group of similar products, we will not split items to 1 since in V18 we import with the quantity itself. Quantity is also a new field in the V18 interface.

 

API TESTING

API testing can be performed using the Postman App. You can download and register for free on the following link.

Link: http://www.getpostman.com/

Last modified

Tags

This page has no custom tags.

Classifications

This page has no classifications.
Powered by CXone Expert ®