Skip to main content
Skip table of contents

OpenInvoice Interface Setup and Configure

Integration Flows

OpenInvoice Setup Items

These items need coordination with open invoice reps for new clients. All items must be completed before QA testing can begin.

  1. OPEN INVOICE - Provide WE with the companyname and dunsnumber for the client that is set up to interface with them - to be added in WE config (this is for AFE/CC sync)

  2. OPEN INVOICE - Create the export job in the test environment so the service status on invoices will get set to pending in OI

  3. OPEN INVOICE/DEVOPS- Need .pem files created/placed in the location specified in the config. It is most commonly stored in /etc/revenue_accounting/

    1. DevOps generates the public key and then gives them to OI, who gives us the .pem and key files. Note: WE Internal environments use the same certs that client test environments use.

    2. Files must be placed in the config-specified directory and have permissions set to read-only. chmod 400

    3. Config will be updated with the specific filenames of the key and .pem files as shown here:

      YAML
      key_path: "/etc/revenue_accounting/client-openinvoice.key"
      cert_path: "/etc/revenue_accounting/client-openinvoice.pem"
      ca_cert_path: "/etc/revenue_accounting/oildexca.pem"
  4. OPEN INVOICE - AFE Types and Cost Center Types need to be set up in the OI Staging environment before the AFE/CC sync. AFE types set up in OI should have their “Name” field match the W Energy AFE types code table and "Code" field value.

  5. OPEN INVOICE - Set up Sites to match Company Names for all the companies setup in the WE App. Note: Sites in OI must match capitalization and punctuation exactly with the company name in WE. (this is for AFE/CC sync, but we have code where we can default to all sites if needed).

  6. OPEN INVOICE – Add WE IP, 104.6.16.177, to OI whitelist - If you need the IP of an AWS box, run the following command on the server as the user wti: dig +short txt ch whoami.cloudflare @1.0.0.1

WE App Setup Items

The WE application needs the following items setup before running the OpenInvoice Sync Processes.

  1. Global Setup/Companies: Create a company with name/number = OI provided companyname if it does not already exist

  2. Global Setup/Chart of Accounts: Add company from step 1 to applicable CoAs

  3. Financial Interface/Interface Sources: Add Code/Description= OpenInvoice/OpenInvoice

  4. Financial Interface/Interface Setup:

    1. Add Journal = AP Invoice and Source = OpenInvoice

    2. Populate the following fields with client-preferred values:

      1. Resolves to Type

      2. Approval Control

      3. Default Role Function

      4. Default Role Type

  5. Code tables/Role Types: Add financial screens to the 'screen uses' for the role type set up in Item 4

  6. GL UOM Code Table: Set a default so if the unit sent in the interface is not in the code table, it will default to one instead of getting rejected

  7. Global Setup/Roles: Vendor Role for Purchase Order must have Delivery Method=OpenInvoice

Notes: CC and AFE MUST be synced from WE before OI Invoices can be created for testing

Config Settings

A top-level config block is needed to enable the OpenInvoice interface with the following information for the specific client.

Config Options

Production and Non-Production Options

payment_response: true

The 'Send Paid Status' button will be shown on the Financial Interface/OpenInvoice Interfaces page and will have the following functionality when the process is run:

  • A response is sent to OI for invoice records that have external_id populated, status=paid, paid_response_paid=null

  • A response is sent to OI for invoice records that have external_id populated, status=voided, paid_response_void=null

sync_invoice_documents: true

From pivotal story #158875603 - If any of the invoices retrieved from OpenInvoice have documents attached, the sync will retrieve the document, unzip, and attach it to its corresponding invoice

Non-Production Options

mimmick_prod: true

This config will mimic the production environment behavior when connecting to one of the non-production OpenInvoice environments, which would only sync each invoice once. running would only sync new invoices.

  • Only 1 environment per client should have this setting enabled

  • When connecting to the prod environment (https://api.openinvoice.com), this happens automatically, and this config option is not needed

fake_server: true

This setting will import invoices from a directory on the VM server. To use this for testing, place invoice files in the import directory under files. The existing implementation of OI that supports multiple OI Companies and DUNS numbers requires a directory per OI Company. For example, it would like this for Terra /srv/www/apps/files/open_invoice/473501850/import. This folder must be created before running the OpenInvoice AP Sync.

Example Settings

Non-Production OI Interface

Note: check if using the onboard-api or uat-api OI sites and replace in URLs.

YAML
oildex:
  flavor: <client>
  payment_response: true
  sync_invoice_documents: true
  afe_url: "https://onboard-api.openinvoice.com/docp/supply-chain/v1/afes"
  cost_center_url: "https://onboard-api.openinvoice.com/docp/supply-chain/v1/cost-centers"
  invoice_url: "https://onboard-api.openinvoice.com/docp/supply-chain/v1/invoices"
  purchase_order_url: "https://onboard-api.openinvoice.com/docp/supply-chain/v1/purchase-orders"
  user_url: "https://onboard-api.openinvoice.com/docp/supply-chain/v1/users"
  key_path: "/etc/revenue_accounting/client-openinvoice.key"
  cert_path: "/etc/revenue_accounting/client-openinvoice.pem"
  ca_cert_path: "/etc/revenue_accounting/oildexca.pem"
  dunsnumber: "OI Provided"
  companyname: “OI Provided”
  mimmick_prod: false
  fake_server: false

Production OI Interface

YAML
oildex:
  flavor: <client>
  payment_response: true
  sync_invoice_documents: true
  afe_url: "https://api.openinvoice.com/docp/supply-chain/v1/afes"
  cost_center_url: "https://api.openinvoice.com/docp/supply-chain/v1/cost-centers"
  invoice_url: “https://api.openinvoice.com/docp/supply-chain/v1/invoices”
  purchase_order_url: "https://api.openinvoice.com/docp/supply-chain/v1/purchase-orders"
  user_url: "https://api.openinvoice.com/docp/supply-chain/v1/users"
  key_path: "/etc/revenue_accounting/client-openinvoice.key"
  cert_path: "/etc/revenue_accounting/client-openinvoice.pem"
  ca_cert_path: "/etc/revenue_accounting/oildexca.pem"
  dunsnumber: "OI Provided"
  companyname: “OI Provided”

OpenInvoice Sync Functionality

The OpenInvoice Sync processes can be run manually from the Financial Interface/OpenInvoice Interfaces page in the WE App or be included in a process schedule set up on the Company Process Control/Process Schedules page in the Application.

Cost Centers Sync to OpenInvoice

From the Financial Interface/OpenInvoice Interfaces page in the WE App, clicking the ‘Sync Cost Centers to OpenInvoice’ button will send Cost Center Information to OpenInvoice for any cost center that has a sync status = NULL or Updated.

Once synced, the following occurs:

  • The Sync Status on the Cost Center is set to ‘Sent’ (cost_centers.sync_status)

    • Note: If OI reports any issues in their response file, the sync status will not be changed to ‘Sent,' allowing the cost center to attempt to sync successfully after the issues are resolved. n example issue would be if they did not have the cost center type defined in their system.

  • The response from OpenInvoice is in XML format. t provides the status of the Sync’d cost center. the response is stored on the application server in the directory /srv/www/apps/files/open_invoice

Example file: response_20200521115111_00039.xml

XML
<?xml version="1.0"?>
<DOResponse application="OpenInvoice" xmIns="http://ww.digitaloilfield.com/ocp">
  <Status>Success</Status>
  <DocumentType>CC</DocumentType>
  <ProcessingDatetime>2020-05-21T10:51:11</ProcessingDatetime>
  <Partner PartnerType="B2BDocumentSender">
    <Company>
      <CompanyCode CompanyCodeType="DUNSnumber">062889134</CompanyCode>
      <CompanyName>Vernon E. Faulconer, Inc.</CompanyName>
    </Company>
  </Partner>
</DOResponse>

AFE Sync to OpenInvoice

From the Financial Interface/OpenInvoice Interfaces page in the WE App, clicking the ‘Sync AFEs to OpenInvoice’ button will send AFE Information to OpenInvoice for any AFE that has a sync status = NULL or Updated AND has a Status of Open, Completed, Closed, or Rejected.

Once synced, the following occurs:

  • The Sync Status on the AFE is set to ‘Sent’ (afe_header.sync_status)

    • Note: If OI reports any issues in their response file, the sync status will not be changed to 'Sent,' allowing the AFE to attempt to sync successfully after the issues are resolved. n example issue would be if they did not have the AFE type defined in their system.

  • The response from OpenInvoice is in XML format. t provides the status of the Sync’d cost center. the response is stored on the application server in the directory /srv/www/apps/files/open_invoice

Example file: response_20200521121142_00001.xml

CODE
<?xml version="1.0"?>
<DOResponse application="OpenInvoice" xmIns="http://ww.digitaloilfield.com/ocp">
  <Status>Success</Status>
  <DocumentType>AFE</DocumentType>
  <ProcessingDatetime>2020-05-21T11:11:42</ProcessingDatetime>
  <Partner PartnerType="B2BDocumentSender">
    <Company>
      <CompanyCode CompanyCodeType="DUNSnumber">062889134</CompanyCode>
      <CompanyName>Vernon E. Faulconer, Inc.</CompanyName>
    </Company>
  </Partner>
</DOResponse>

OpenInvoice AP Sync

From the Financial Interface/OpenInvoice Interfaces page in the WE App, there are two ways the user can initiate the AP invoice Sync.

  • The ‘OpenInvoice AP Sync’ button will pull all available invoices from OpenInvoice through the interface and create matching AP Invoices in the WE Application. The Sync’d invoice.xml files are saved on the application server in the /srv/www/apps/files/open_invoice directory.

  • The ‘Retrieve Single Invoice’ button will pull a single invoice from OpenInvoice through the interface and create a matching AP Invoice in the WE Application. The user is prompted via a pop-up for the OpenInvoice Invoice ID when this button is clicked. The value to enter in the field depends on the config setting as follows:

    • Config setting of fake_server: true - Enter the Invoice XML filename without the extension.

Example for invoice named invoice_Test520204-3.xml

Config setting of fake_server: false (default) - Enter the ImageInvoice ID from the invoice XML file. This value matches the ID that OpenInvoice uses to identify the invoice.

XML
<?xml version="1.0" encoding="UTF-8"?>
<SupplierConnectInvoice xmlns="http://www.digitaloilfield.com/xml/ns/ocp" type="APINVOICE">
  <ImageInvoice id="59460263">
    <InvoiceHeader>
      <InvoiceNumber>Test 520204</InvoiceNumber>
      <Partner PartnerType="Supplier" />
      <Company>
        <CompanyCode CompanyCodeType="VendorNumber">123456789</CompanyCode>
        <CompanyName>Vernon E Faulconer Supplier Test</CompanyName>
      </Company>
    </InvoiceHeader>
    ...
  </ImageInvoice>
</SupplierConnectInvoice>

Invoice ID copied from XML document’s ImageInvoice/id.

Sent Paid Status

From the Financial Interface/OpenInvoice Interfaces page in the WE App, the ‘Send Paid Status’ button will send an updated JSON file to OI for any AP Invoice that was synced from OI and has been paid or voided.

  • AP Payment released for an AP Invoice with source = OpenInvoice, status= Paid, external ID = OpenInvoice Invoice ID.

    • WE sends updated json to OI: update_20200521155337-1.json

OI sends response XML back: response_20200521035338_00001.xml

  • Previous AP Payment Voided and released.

    • WE sends updated json to OI: update_20200521161827-1.json

OI sends response XML back: response_20200521041828_00001.xml

Additional OpenInvoice Sync Functionality

  • AFE - DOI Sync (Pivotal Story #163037544): The process button is on the AFE/AFEs page

  • User Sync (Pivotal Story #163461083): The sync button is on the OpenInvoice /Interfaces page

    • It can only be used if a client uses the Labor Distribution module because users will not sync if they do not have the required fields:

      • AuthorizationDollarLimit approval_title_users.dollar_limit

      • ParentApprover exd_ap_employees.supervisor_id

  • Purchase Order Sync (Pivotal Story #172342135): No ‘Sync’ Button – XML file is created when the PO has status = sent and vendor role has delivery method = OpenInvoice

    • On the Purchase order, the Instruction Type will need to be one of the following values (they are added via migration to the Purchase Order Instruction Type code table):

      • CarrierInstructions

      • ConsigneeInstructions

      • DriverInstructions

      • EmptyReturnInstructions

      • InspectionsInstructions

      • RoutingInstructions

      • ShipperInstructions

      • ShortLeadTime

      • ShortLeadTimeInstructions

      • Tolerances

      • Other

    • Internal testing with fake_server config enabled

      • Even with Fake Server enabled, the Vendor Role on the PO must have its Delivery Method set to OpenInvoice (‘OpenInvoice’ is added via migration to the Delivery Method code table) to generate the XML.

      • In Fake Server mode, it will always return no errors and report as the PO being accepted by OpenInvoice.

    • When PO meets the OpenInvoice criteria and is sent, an XML file is created and sent to OI. the XML file that WE sends to OI can be found on the server: /srv/www/apps/files/open_invoice/purchase_order

    • When OI receives the PO, they will send back a status XML with the status.

Various Functionality for Possible Cherry Pick

There have been some customizations on specific client branches that may need to be considered as an addition to code branches depending on what the resulting code branch was branched from. Or example, if the client is one of EAG’s clients, their flavor would branch from an EAG branch, and the functionality listed below with (7.5.3.eag) denoted would already be in their code, so no cherry-pick would be needed.

  • #172096094 - Create an open_invoice directory if it does not exist (7.5.3.flywheel)

  • #172386312 - Send Time with Payment Date on OI Paid Status Sync (7.5.4.flywheel)

  • #171934512 - Flywheel AP Invoice Activity Date and UOM Mapping Adjustment (7.5.3.flywheel)

    • GL Dist activity date is pulled from the ServiceDate or the Value of the override (AdditionalData) Service Date from the invoice details sections of the XML

    • The Header activity date is the earliest of the GL Dist activity dates

  • #172090058 - Do not remove characters from Invoice Number (7.5.3.eag)

  • #172213671 - Allow creation of Invoice Number with more special characters (7.5.3.eag)

  • #172257459 - Change Company Source from OpenInvoice (8.1.0.water)

    • Change the mapping of the Company Code to pull from SiteName instead of CompanyName

    • Currently, this is only implemented if the DB clients.name= H2O

  • #172383540 - Update POs and AP Invoices for OI Integration (8.1.1.water)

    • Config driven.

      • features.bypass_po_matching: true

    • PO/AP Invoice matching is not done in WE when the config is true. PO will be attached to the Sync’d AP Invoice if it exists in WE, and there will be no matching validations when submitted.

  • #173503527 - Modify AP Invoice OI Sync Logic (8.1.1.water)

    • Config driven

      • Oildex.use_earliest_account_period: true

    • Modify accounting date on AP Invoice Sync, set to the last day of the month based on open accounting periods (current month +/- 1 month)

    • If the Invoice fails to be created in WE, do not send the json response file.

Example CURL Command

BASH
curl -v -k \
  "https://onboard-api.openinvoice.com/docp/supply-chain/v1/invoices?$filter=status+eq+approved+and+lastActionDate+ge+2018-12-31&$count=true" \
  --key /etc/revenue_accounting/dugan-openinvoice.key \
  --cert /etc/revenue_accounting/dugan-openinvoice.pem \
  --cacert /etc/revenue_accounting/openinvoice-ca.pem

Its output

CODE
* About to connect() to onboard-api.openinvoice.com port 443 (#0)
*   Trying 161.38.178.130...
* Connected to onboard-api.openinvoice.com (161.38.178.130) port 443 (#0)
* Initializing NSS with certpath: sql:/etc/pki/nssdb
* skipping SSL peer certificate verification
* NSS: client certificate from file
* 	subject: E=devops@wenergysoftware.com,CN=dugan.wenergysoftware.com,OU=Dugan,O="W Energy Software, LLC",L=Tulsa,ST=Oklahoma,C=US
* 	start date: Aug 16 16:36:24 2022 GMT
* 	expire date: Sep 17 16:36:24 2023 GMT
* 	common name: dugan.wenergysoftware.com
* 	issuer: E=apsitrequest@adp.com,CN=P2P Certificate Authority,OU=Procure-To-Pay,O=ADP Inc.,L=Calgary,ST=Alberta,C=CA
* SSL connection using TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
* Server certificate:
* 	subject: CN=api.openinvoice.com,O="Enverus (Enverus, Inc.)",L=Austin,ST=Texas,C=US,serialNumber=155356300,businessCategory=Private Organization,incorporationState=Texas,incorporationCountry=US
* 	start date: Apr 18 00:00:00 2022 GMT
* 	expire date: Apr 18 23:59:59 2023 GMT
* 	common name: api.openinvoice.com
* 	issuer: CN=DigiCert SHA2 Extended Validation Server CA,OU=www.digicert.com,O=DigiCert Inc,C=US
> GET /docp/supply-chain/v1/invoices?=status+eq+approved+and+lastActionDate+ge+2018-12-31&=true HTTP/1.1
> User-Agent: curl/7.29.0
> Host: onboard-api.openinvoice.com
> Accept: */*
>
< HTTP/1.1 200
< Set-Cookie: DO2SESSIONID=2319750FC049A29A9E9F9C12C95FB44D; Path=/docp; Secure; HttpOnly
< Cache-Control: no-cache, no-store, max-age=0, must-revalidate
< Pragma: no-cache
< Expires: 0
< Strict-Transport-Security: max-age=31536000 ; includeSubDomains
< X-XSS-Protection: 1; mode=block
< X-Frame-Options: DENY
< X-Content-Type-Options: nosniff
< vary: accept-encoding
< Content-Type: application/json;charset=UTF-8
< Content-Length: 6918
< Date: Wed, 02 Nov 2022 14:40:27 GMT
< Server: REDACTED
<
{"invoices":[ ... ]}

API Documentation and Example Files

File Modified

PDF File AFE and Cost Center - API.pdf

Mar 31, 2023

XML File afe_example_response.xml

Mar 31, 2023

XML File API AFE_Import.xml

Mar 31, 2023

XML File API CC_Import.xml

Mar 31, 2023

XML File Invoice Example - Lucero.xml

Mar 31, 2023

PDF File OpenInvoice - Integration Flows.pdf

Mar 31, 2023

PDF File OpenInvoice API.pdf

Mar 31, 2023

PDF File OpenInvoice APIs for Suppliers.pdf

Mar 31, 2023

PDF File PO Import API.pdf

Mar 31, 2023

PDF File User Import.pdf

Mar 31, 2023
JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.