Libraries & Examples – interworks.cloud Portal

Table of Contents

1 Libraries
- 1.1 OpenAPI-Specification
- 1.2 JUST
2 Extension of OpenAPI
- 2.1 A JSON Instance Example

This page includes references to libraries used by the integration framework as well as some examples of their use.

Libraries

OpenAPI-Specification

The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined, a consumer can understand and interact with the remote service with a minimal amount of implementation logic.

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md

JUST

JUST Stands for JSON Under Simple Transformation

A library in .NET which enables the transformation of JSON documents using very a simple transformation language.

https://github.com/WorkMaze/JUST.net

Extension of OpenAPI

In order to accomplish system data synchronization from BSS we extend the specification with a new elements

"Invoice": {
      "description": "Synchronize Invoices with 3rd party system",
      "module": "Invoices",
      "push": {
        "create": "/SalesInvoice/post",
        "update": "/SalesInvoice(No='{IntegrationId}',Document_Type='Invoice')/put",
        "preSynchronizationAction": {
          "ETag": {
            "type": "ApiPath",
            "path": "/SalesInvoice(No='{IntegrationId}',Document_Type='Invoice')/get",
            "schema": {
              "type": "String",
              "ETag": "ETag"
            },
            "in": "Body"
          },
          "HeaderETag": {
            "type": "ApiPath",
            "path": "/SalesInvoice(No='{IntegrationId}',Document_Type='Invoice')/get",
            "schema": {
              "type": "String",
              "header": "If-Match",
              "headerValue": "@odata.etag"
            },
            "in": "Header"
          }
        },
        "postSynchronizationAction": {
          "InvoiceItems": {
            "type": "ApiSynchronization",
            "path": "InvoiceItems",
            "schema": {
              "type": "String",
              "ETag": "ETag"
            },
            "in": "Body"
          }
        },
        "schemasTransformer": {
                       "Document_Type": "Invoice",
                       "Sell_to_Customer_Name": "#valueof($.invoice.account.name)",
                       "Sell_to_Address": "#valueof($.invoice.account.addresses[?(@.isBilling==true)].address1)",
                       "Sell_to_Address_2": "#valueof($.invoice.account.addresses[?(@.isBilling==true)].address2)",
                       "Sell_to_Post_Code": "#valueof($.invoice.account.addresses[?(@.isBilling==true)].postCode)",
                       "Sell_to_City": "#valueof($.invoice.account.addresses[?(@.isBilling==true)].city)",
                       "Document_Date": "#valueof($.invoice.createdAt)",
                       "Due_Date": "#valueof($.invoice.dueDate)",
                       "Currency_Code": "#valueof($.invoice.billingAccount.accountCurrency.currency.mnemonic)"
            }
      }
    }

A JSON Instance Example

{
  "openapi": "3.0.0",
  "info": {
    "title": "Quickbooks integration",
    "contact": {
      "name": "Thomas Zisopoulos"
    },
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://sandbox-quickbooks.api.intuit.com/v3/company/193514681960574",
      "description": "Sandbox",
      "variables": {
        "Vendor_ID": {
          "default": "196",
          "description": "Vendor account ID on QB"
        },
        "Vendor_Name": {
          "default": "Interworks Cloud",
          "description": "Vendor account name on QB"
        }
      }
    }
  ],
  "paths": {
    "/customer": {
      "post": {
        "description": "Creates a new account in the system.",
        "requestBody": {
          "description": "Account to add to the system",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/account"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Account response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/newRecord"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "account": {
        "type": "object",
        "required": [
          "GivenName"
        ],
        "properties": {
          "Id": {
            "type": "string"
          },
          "SyncToken": {
            "type": "string"
          },
          "MetaData": {
            "type": "object"
          },
          "GivenName": {
            "type": "string"
          },
          "DisplayName": {
            "type": "string"
          },
          "PrimaryPhone": {
            "type": "object"
          },
          "Fax": {
            "type": "object"
          },
          "PrimaryEmailAddr": {
            "type": "object"
          },
          "WebAddr": {
            "type": "object"
          },
          "Taxable": {
            "type": "boolean"
          },
          "TaxExemptionReasonId": {
            "type": "string"
          },
          "BillAddr": {
            "type": "object"
          },
          "CurrencyRef": {
            "type": "object"
          },
          "Sparse": {
            "type": "boolean"
          }
        }
      },
      "newRecord": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "format": "int64"
          },
          "errors": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "success": {
            "type": "boolean"
          }
        }
      }
    },
    "securitySchemes": {
      "oauth2_auth": {
        "type": "oauth2",
        "description": "OAuth2 Authentication",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://appcenter.intuit.com/connect/oauth2",
            "tokenUrl": "https://oauth.platform.intuit.com/oauth2/v1/tokens/bearer ",
            "scopes": {
              "com.intuit.quickbooks.accounting": "QuickBooks Online API",
              "com.intuit.quickbooks.payment": "QuickBooks Payments API"
            }
          }
        }
      }
    }
  },
  "synchronization": {
    "Accounts": {
      "description": "Accounts",
      "module": "Accounts",
      "push": {
        "create": "/customer/post",
        "update": "/customer/post",
        "preSynchronizationAction": {
          "SyncToken": {
            "type": "ApiPath",
            "path": "/customer/{Account.IntegrationId}/get",
            "schema": {
              "type": "String",
              "SyncToken": "Customer.SyncToken"
            },
            "in": "Body"
          }
        },
        "schemasTransformer": {
          "accountRequest": "{\"GivenName\":\"#valueof($.account.name)\",\"PrimaryPhone\":{\"FreeFormNumber\":\"#valueof($.account.phone)\"},\"Fax\":{\"FreeFormNumber\":\"#valueof($.account.fax)\"},\"PrimaryEmailAddr\":{\"Address\":\"#valueof($.account.corpEmail)\"},\"WebAddr\":{\"URI\":\"#valueof($.account.webSite)\"},\"BillAddr\":{\"Line1\":\"#valueof($.account.addresses[?(@.isBilling==true)].address1)\",\"Line2\":\"#valueof($.account.addresses[?(@.isBilling==true)].address2)\",\"City\":\"#valueof($.account.addresses[?(@.isBilling==true)].city)\",\"Country\":\"#valueof($.account.addresses[?(@.isBilling==true)].countryName)\",\"PostalCode\":\"#valueof($.account.addresses[?(@.isBilling==true)].postCode)\",\"CountrySubDivisionCode\":\"#valueof($.account.addresses[?(@.isBilling==true)].region)\"},\"Taxable\":\"#valueof($.account.isTaxable)\",\"TaxExemptionReasonId\":\"#valueof($.serverVariables.tax_Exception_Reason)\",\"CurrencyRef\":{\"value\":\"#ifcondition(#valueof($.account.accountCurrency),NULL,,#valueof($.account.accountCurrency.currency.mnemonic))\",\"name\":\"#ifcondition(#valueof($.account.accountCurrency),NULL,,#valueof($.account.accountCurrency.currency.name))\"},\"MetaData\":{\"CreateTime\":\"#valueof($.account.createdAt)\",\"LastUpdatedTime\":\"#valueof($.account.updatedAt)\"}}",
          "accountUpdateRequest": "{\"SyncToken\":\"#valueof($.syncToken)\",\"Id\":\"#valueof($.externalId)\",\"GivenName\":\"#valueof($.account.name)\",\"PrimaryPhone\":{\"FreeFormNumber\":\"#valueof($.account.phone)\"},\"Fax\":{\"FreeFormNumber\":\"#valueof($.account.fax)\"},\"PrimaryEmailAddr\":{\"Address\":\"#valueof($.account.corpEmail)\"},\"WebAddr\":{\"URI\":\"#valueof($.account.webSite)\"},\"BillAddr\":{\"Line1\":\"#valueof($.account.addresses[?(@.isBilling==true)].address1)\",\"Line2\":\"#valueof($.account.addresses[?(@.isBilling==true)].address2)\",\"City\":\"#valueof($.account.addresses[?(@.isBilling==true)].city)\",\"Country\":\"#valueof($.account.addresses[?(@.isBilling==true)].countryName)\",\"PostalCode\":\"#valueof($.account.addresses[?(@.isBilling==true)].postCode)\",\"CountrySubDivisionCode\":\"#valueof($.account.addresses[?(@.isBilling==true)].region)\"},\"Taxable\":\"#valueof($.account.isTaxable)\",\"TaxExemptionReasonId\":\"#valueof($.serverVariables.tax_Exception_Reason)\",\"CurrencyRef\":{\"value\":\"#ifcondition(#valueof($.account.accountCurrency),NULL,,#valueof($.account.accountCurrency.currency.mnemonic))\",\"name\":\"#ifcondition(#valueof($.account.accountCurrency),NULL,,#valueof($.account.accountCurrency.currency.name))\"},\"MetaData\":{\"CreateTime\":\"#valueof($.account.createdAt)\",\"LastUpdatedTime\":\"#valueof($.account.updatedAt)\"},\"sparse\":true}",
          "newRecordResponse": "{\"id\":\"#valueof($.Customer.Id)\"}"
        }
      }
    }
  },
  "security": [
    {
      "oauth2_auth": [
        "com.intuit.quickbooks.accounting",
        "com.intuit.quickbooks.payment"
      ]
    }
  ]
}