IFS Connector Administrator and User Guide
- IFS Energy and Resources (Deactivated)
- IFS Energy & Resources (Deactivated)
- Bobby Lo (Unlicensed)
Back to IFS BOLO and IFS Land Installation & Configuration
Introduction to IFS Connector
Welcome to IFS Connector. IFS Connector allows for interoperability between the IFS Merrick ProCount (volume accounting software) and IFS Enterprise Upstream (revenue and financial accounting system) applications. Interoperability means that data can be transferred from Enterprise Upstream to ProCount and vice-versa.
The IFS Connector consists of the following three components: the IFS Connector Client Console Application, the IFS Connector Windows Service, and the IFS Connector Dashboard (website). The customer may pick and choose which components to install. For additional information, refer to IFS Connector Installation & Configuration.
This user guide contains detailed information about how IFS Connector is configured, deployed, used, and maintained.
Assumptions and Constraints
IFS Connector Windows Service is only compatible with IFS Merrick ProCount 2012.3.0 (or Higher).
IFS Connector Windows Service is only compatible with EU version 12.46.0xA REST API (or Higher).
IFS Connector Windows Service can handle multiple instances of ProCount for the same customer, but the customer still has the option to install multiple instances of IFS Connector to handle each ProCount instance separately.
All dates are saved in UTC in the IFS Connector Window Service’s database and IFS Connector Client Console Application database.
If IFS Connector Windows Service failed to process a request at any point of execution, it will not try to re-execute the same request unless it gets scheduled again by IFS Task Scheduler.
IFS Connector Windows Service will execute the requests sequentially (one-by-one) as they were queued in the Service Bus Message Queue.
IFS Connector Windows Service and IFS Connector Console Application use only one preconfigured Message Queue per installed instance.
Interop Software Modules
The importance of software modules for interop is illustrated by the diagram below. In order for the interop to work correctly and start transferring data between the IFS ProCount and IFS Enterprise Upstream systems, we need its respective software modules to be set up correctly. Refer to the subsection below for setup instructions.
Interop Software Modules Setup
The administrator should refer to the table below to ensure each interop software module meets the applicable system and setup requirements.
Module | Module Description/Setup Requirements | System Requirements |
|---|---|---|
IFS Connector Client Console Application | This is a console app that allows the IFS Task Scheduler to send messages to Microsoft Service Bus. |
|
IFS Connector Windows Service | This is a Windows service that retrieves requests queued into its Message Queue, executes the command by pulling and pushing the data from EU and ProCount via APIs, based on the request rules. This service will notify other systems of the success or failure of the executed request. |
|
IFS Connector Dashboard (Website) | This is a Web Portal to view the IFS Connector Windows Service, IFS Connector Client Console Application, and system statuses and logs. |
|
IFS Task Scheduler | Ensure schedules are set up to schedule commands to the Connector. Refer to the Task Scheduler Administrator Guide for additional information. | Refer to the Task Scheduler Installation Guide for system requirements information. |
ProCount API | Ensure the ProCount API (WCF Service) is correctly set up for each ProCount instance. Refer to the IFS Merrick 2012 Installation Guide for additional information. | Refer to the IFS Merrick 2012 Installation Guide for system requirements. |
EU API | Ensure the EU API (REST Service) is correctly set up. Refer to the EU Installation Guide for additional information. | Refer to the EU Installation Guide for system requirements. |
IFS AFE API | Ensure the IFS AFE API (REST Service) is correctly set up. Refer to the IFS AFE Interoperability Settings for additional information. | Refer to the IFS AFE Interoperability Settings for system requirements. |
BOLO API | Ensure the BOLO API (REST Service) is correctly set up. Refer to the BOLO Installation Guide for additional information. | Refer to the IFS BOLO Installation Guide for system requirements. |
IFS Land API | Ensure the IFS Land API (REST Service) is correctly set up. Refer to the IFS Land Installation Guide for additional information. | Refer to the IFS Land Installation Guide for system requirements available with the IFS Land releases through the P2 Store. |
Data Mapping
IFS Connector Client Console Application
The IFS Connector Client Console Application can queue (send) messages (requests) to the IFS Connector Message Queue.
After queuing the request in the IFS Connector Message Queue, the console app will record the request in an auditing table in the SQL Server database. The database table is part of the IFS Connector Windows Service database. The database connection string is saved in the P2.Services.Connector.Client.exe.config file.
The IFS Connector Client Console Application will accept certain parameters that will determine the request message contents.
Parameter | Acceptable Input | Required | Default Value (If not included) | Possible Values | Description |
|---|---|---|---|---|---|
-S | Numeric Only | Yes | No Default Value | 1 or 2
| This parameter communicates to the IFS Connector Windows Service that the request was either scheduled or ran manually. Note: This field will be used differently in the future releases. |
-r | Numeric Only | Yes | No Default Value | Refer to the Route Table below | This parameter communicates to the IFS Connector Windows Service which Request Route ID to execute. |
-i | Alpha Only | No | False | False | This parameter communicates to the IFS Connector Windows Service if his request was scheduled or not. |
-v | Alpha Only | No | True | False | This parameter communicates to the IFS Connector Console Application to print all messages to screen (Verbose Mode). |
The following Route Request table contains all the possible Request Routes that the administrator can schedule the IFS Connector Windows Service with using this IFS Connector Client Console Application:
REQUEST ROUTE ID | REQUEST ROUTE DESCRIPTION | IFS PROCOUNT SITE |
|---|---|---|
10 | Connector Status Update | All |
100 | Wells and Completions | 1 |
110 | Completions Producing Status | 1 |
200 | Business Entities and Locations (Parties and Sites) | 1 |
300 | Completion Daily Dispositions (EDD) | 1 |
310 | Completion Daily Summarized Volumes | 1 |
400 | Completion Monthly Dispositions (APT) | 1 |
500 | Completion Monthly Dispositions Used by Accounting Flag | 1 |
1000 | Wells and Completions | 2 |
1100 | Completions Producing Status | 2 |
2000 | Business Entities and Locations (Parties and Sites) | 2 |
3000 | Completion Daily Dispositions (EDD) | 2 |
3010 | Completion Daily Summarized Volumes | 2 |
4000 | Completion Monthly Dispositions (APT) | 2 |
5000 | Completion Monthly Dispositions Used by Accounting Flag | 2 |
10000 | Wells and Completions | 3 |
11000 | Completions Producing Status | 3 |
20000 | Business Entities and Locations (Parties and Sites) | 3 |
30000 | Completion Daily Dispositions (EDD) | 3 |
30010 | Completion Daily Summarized Volumes | 3 |
40000 | Completion Monthly Dispositions (APT) | 3 |
50000 | Completion Monthly Dispositions Used by Accounting Flag | 3 |
100000 | Wells and Completions | 4 |
110000 | Completion Producing Status | 4 |
200000 | Business Entities and Locations (Parties and Sites) | 4 |
300000 | Completion Daily Dispositions (EDD) | 4 |
300010 | Completion Daily Summarized Volumes | 4 |
400000 | Completion Monthly Dispositions (APT) | 4 |
500000 | Completion Monthly Dispositions Used by Accounting Flag | 4 |
For example, to schedule a manual update to Wells and Completions for ProCount Site 2, run the following command:
Sample manual request command:
Sample scheduled request command:
Scheduling Tasks for IFS Connector
In order for the IFS Connector Windows Service to start processing requests, scheduled tasks need to be created for each information route. The following information routes are available for IFS Connector:
Wells and Completions Route
Completions Producing Status Update Route
Business Entities and Business Entity Locations (Parties and Sites) Route
Completion Daily Dispositions (EDD) Route
Completion Monthly Dispositions and Total Productions (APT) Route
Completion Monthly Dispositions Used by Accounting Flags Update Route
Each route can be scheduled weekly, daily, or hourly based on your business needs. The schedule needs to be repeated for each ProCount site. The following table has the suggested schedule, it can be changed based on your business requirements:
INFORMATION ROUTE | IFS PROCOUNT SITE | SCHEDULE FREQUENCY | TASK SCHEDULER AND COMMAND PARAMETERS |
|---|---|---|---|
Wells and Completions Route | Site 1 | Daily at 9:00 PM | -s 2 -r 100 -i true |
Completions Producing Status Update Route | Site 1 | Daily at 10:00 PM | -s 2 -r 110 -i true |
Business Entities and Business Entity Locations (Parties and Sites) Route | Site 1 | Daily at 8:00 PM | -s 2 -r 200 -i true |
Completion Daily Dispositions (EDD) Route | Site 1 | Daily at 3:30 AM | -s 2 -r 300 -i true |
Completion Daily Summarized Volumes | Site 1 | Daily at 3:30 AM | -s 2 -r 310 -i true |
Completion Monthly Dispositions and Total Productions (APT) Route | Site 1 | Weekly Every Saturday at 1:00 AM | -s 2 -r 400 -i true |
Completion Monthly Dispositions Used by Accounting Flags Update Route | Site 1 | Daily at 11:00 PM | -s 2 -r 500 -i true |
Wells and Completions Route | Site 2 | Daily at 9:15 PM | -s 2 -r 1000 -i true |
Completions Producing Status Update Route | Site 2 | Daily at 10:15 PM | -s 2 -r 1100 -i true |
Business Entities and Business Entity Locations (Parties and Sites) Route | Site 2 | Daily at 8:15 PM | -s 2 -r 2000 -i true |
Completion Daily Dispositions (EDD) Route | Site 2 | Daily at 4:30 AM | -s 2 -r 3000 -i true |
Completion Daily Summarized Volumes | Site 2 | Daily at 4:30 AM | -s 2 -r 3010 -i true |
Completion Monthly Dispositions and Total Productions (APT) Route | Site 2 | Weekly Every Saturday at 2:00 AM | -s 2 -r 4000 -i true |
Completion Monthly Dispositions Used by Accounting Flags Update Route | Site 2 | Daily at 11:15 PM | -s 2 -r 5000 -i true |
Wells and Completions Route | Site 3 | Daily at 9:30 PM | -s 2 -r 10000 -i true |
Completions Producing Status Update Route | Site 3 | Daily at 10:30 PM | -s 2 -r 11000 -i true |
Business Entities and Business Entity Locations (Parties and Sites) Route | Site 3 | Daily at 8:30 PM | -s 2 -r 20000 -i true |
Completion Daily Dispositions (EDD) Route | Site 3 | Daily at 5:30 AM | -s 2 -r 30000 -i true |
Completion Daily Summarized Volumes | Site 3 | Daily at 5:30 AM | -s 2 -r 30010 -i true |
Completion Monthly Dispositions and Total Productions (APT) Route | Site 3 | Weekly Every Saturday at 3:00 AM | -s 2 -r 40000 -i true |
Completion Monthly Dispositions Used by Accounting Flags Update Route | Site 3 | Daily at 11:30 PM | -s 2 -r 50000 -i true |
Wells and Completions Route | Site 4 | Daily at 9:15 PM | -s 2 -r 100000 -i true |
Completions Producing Status Update Route | Site 4 | Daily at 10:15 PM | -s 2 -r 110000 -i true |
Business Entities and Business Entity Locations (Parties and Sites) Route | Site 4 | Daily at 8:15 PM | -s 2 -r 200000 -i true |
Completion Daily Dispositions (EDD) Route | Site 4 | Daily at 4:30 AM | -s 2 -r 300000 -i true |
Completion Daily Summarized Volumes | Site 4 | Daily at 4:30 AM | -s 2 -r 300010 -i true |
Completion Monthly Dispositions and Total Productions (APT) Route | Site 4 | Weekly Every Saturday at 4:00 AM | -s 2 -r 400000 -i true |
Completion Monthly Dispositions Used by Accounting Flags Update Route | Site 4 | Daily at 11:15 PM | -s 2 -r 500000 -i true |
The IFS Connector Windows Service will execute the requests sequentially based on first come first serve, and not in parallel. In other words, IFS Connector will process one request at a time.
IFS Connector Windows Service
IFS Connector Windows Service is a Windows service that needs to run on a Windows Server under the Local System account. The IFS Connector Windows Service is the heart of this interop solution as it processes IFS Task Scheduler requests and exchanges data among systems. The IFS Connector Windows Service is designed to connect to multiple IFS ProCount and IFS EU systems.
The IFS Connector Windows Service will connect to IFS ProCount via IFS ProCount WCF API Service and to IFS Enterprise Upstream via its REST API service.
The IFS Connector Windows Service should be able to access the following endpoints:
All IFS ProCount instances WCF API Services.
All EU REST API Services.
The Connector SQL Server database.
The P2.Services.Connector.WindowsService.exe.config file contains the frequency that the IFS Connector Windows Service should run for the following services:
How often the IFS Connector Windows Service will pull a message from the message queue in seconds. The default is 30 seconds.
How often the IFS Connector Windows Service will check the status of the endpoints that the dashboard requires to check the system health in seconds. The default is 60 seconds.
To debug an issue with the service, the administrator can turn on debugging in the configuration file to start seeing the debug audit messages in the dashboard. The valid values for the Debugging application setting are On or Off.
The IFS Connector Windows Service should be running at all times and should not be stopped unless the software needs to be patched or for server regular maintenance. If the IFS Connector Windows Service was down for any reason, it will pick up all the queued messages and continue its work without issues.
One instance of IFS Connector Windows Service can be used to serve all ProCount instances in your company, but if desired, the customer may elect to install multiple instances on different servers, or the same server, to serve each ProCount instance. If installing multiple instances, a different IFS Connector database will be needed for each IFS Connector instance.
The IFS Connector Windows Service contains an internal Notification Service. Notification service is an important part of the IFS Connector solution as it will notify systems with the status of their data exchange process.
If the IFS Connector Windows Service was successful in data exchange, then the Notification Service will notify the source system that the data push was successful. On the other hand, if the push had an error, the Notification Service will send a failed status to the source system along with the error message.
The notification will be on the object level. For example, when inserting multiple completions, the notification service will notify the source system about the success or failure for each and every completion, as well as the respective reason for each success or failure, not for the whole process.
If the IFS Connector Windows Service process failed to push the data to the destination system based on the request, it will not notify the source system with the results, and it will wait for the next request to try again. If the IFS Connector Windows Service failed to push the data to the destination, then it will record audit messages in the database.
Configuring the IFS Connector Windows Service Systems
Currently the IFS Connector Windows Service does not have a user interface to configure the IFS Connector Window Service’s systems. The only way for the administrator to configure the systems is to change them in the database directly. The database table that needs to be edited is P2System. After seeding the database (see IFS Connector Installation & Configuration), the administrator should edit the P2System table (required). The initial P2System table appears as follows:
The administrator should change the System Service URI values and the Security Token values as well. If your system needs to have a useful name to show in the IFS Connector Dashboard (website), then update the system name to a useful name that your users will understand.
Please consult with IFS Merrick Customer Support if you have any issues setting up these values.
Event Viewer
The IFS Connector Windows Service will report service operation activities to the Windows Application Event Log. You can access the Windows Event Log via the Event Viewer application that is bundled with every Windows operating system. Check the Application log for events coming from Connector Service source.
IFS Connector Dashboard (Website)
The IFS Connector Dashboard is a website contains a dashboard that will allow IFS EU and IFS ProCount users check the health status of the IFS Connector’s various connected systems and will allow users to see the IFS Connector’s different systems log messages.
The IFS Connector Dashboard website will be open, meaning that the site will not enforce authentication or authorization for employees within your company to access it. This web-based dashboard will be accessed by ProCount and EU users via a link inside each product. The product can customize the URL to automatically filter the dashboard for its area of interest.
The IFS Connector Dashboard website will have a menu of tabs that will navigate the user among pages. The menu will have the following tabs:
Dashboard: Return to dashboard homepage.
Connector Log: Navigates to Connector Request Log page.
Connector Client Log: Navigates to Connector Client Log page.
Dashboard Tab
If the Dashboard tab is selected, the dashboard homepage appears. As shown above, the dashboard homepage contains the following areas:
1. System Status
2. Today’s Activity Report
IFS EU and IFS ProCount users can check the health status of the following services in the System Status box:
IFS Connector Service Status
Notification Service Status
IFS Connector Database Status
IFS ProCount WCF Service Status for all ProCount Instances
IFS Enterprise Upstream REST API Status
A summary of the current day’s activity will display in the Today’s Activity Report box:
Interop Errors Counter
Interop Warnings Counter
Network Errors Counter
Processed Request Counter
Connector Log Tab
The Connector Log can filter the log by the following filter criteria:
SEARCH CRITERIA | POSSIBLE VALUES | FILTER TYPE | DESCRIPTION |
|---|---|---|---|
System |
| Multi-Select List Box | This filter will narrow down the search for a specific system or multiple systems. |
Request Route | The values of this search criteria will come from the RequestRoute table. | Multi-Select List Box | This filter will narrow down the search for a specific request route or request routes. |
Process Status | The values of this search criteria will come from the RequestRoute table. | Multi-Select List Box | This filter will narrow down the search for a specific request processing status or request processing statuses. |
From Date | Date & Time | DateTime Picker | Search from specific date. |
To Date | Date & Time | DateTime Picker | Search until specific date. |
Free Text Search | Alpha-numeric | Text Box | Free text search for any field. |
Maximum From/To Date Range
The range between the From Date and To Date fields in the Connector Log or Connector Client Log tab is limited to 7 days by default. This limit is set to prevent the Dashboard from returning a huge amount of data for a search performed in these tabs. This limit can be manually changed for the whole website in the Web.Config file on the root folder of the Dashboard website. To change the limit, look for the <appSettings> tag and the MaxQueryDaysRange key and change this value to any desired number of days to limit the search date range. Valid numbers are between 1 to 365 (days). If a date range that surpasses the limit is entered, an error message will display when the user tries to search.
Connector Client Log Tab
The Connector Client Log can filter the log by the following filter criteria:
SEARCH CRITERIA | POSSIBLE VALUES | FILTER TYPE | DESCRIPTION |
|---|---|---|---|
Request Route | The values of this search criteria will come from the RequestRoute table. | Multi-Select List Box | This filter will narrow down the search for a specific request route or all request routes. |
Request Source | The values of this search criteria will come from the RequestSource table. | Multi-Select List Box. | This filter will narrow down the search for a specific request source or all request sources. |
From Date | Date & Time | DateTime Picker | Search from specific date. |
To Date | Date & Time | DateTime Picker | Search until specific date. |
Free Text Search | Alpha-numeric | Text Box | Free text search for any field. |
Maximum From/To Date Range
Refer to the Maximum From/To Date Range subsection above for detailed information.
Copyright© 2024 IFS AB. Copying prohibited. All rights reserved.