TheTechIdea OilGas - User guide Developer guide →

Setting up a company (data manager's guide)

A company's environment says how its data maps onto the views: its country conventions, its data sources and code values, its equipment and symbols, its stratigraphy, lithologies, log mnemonics and tubulars - and the checks that prove it all resolves. Everything below lives in the environment and the files it names; nothing needs code. Work through the steps in order; the wellbore-config tool reports what is still missing at each step.

The setup app (tools/setup-app, Windows) walks through the same steps with their state, lets you resolve each unresolved value by choosing what it means, previews a well in the real views and writes every change at once. A company database joins through a plugin: a DLL with an IDataSourceFactory in the app's plugins folder. On any platform, and in scripts, the same operations are wellbore-config setup commands - setup new, setup source, setup status (the steps and their state; exit 1 until all are done), setup map, setup import-worksheet, setup unit, setup top, setup unit-alias, setup mnemonic-alias, setup symbol, setup capture and setup handover.

Where everything is

The tool knows where every configuration and example is and writes it out for you, so nothing has to be hunted for in a source tree. These work from an installed tool as well as from a checkout:

wellbore-config where                                    # everything, and the command that writes each
wellbore-config samples                                  # the samples and mapping profiles, with what each shows
wellbore-config samples kuwait.environment.sample.json company/kuwait.json
wellbore-config samples KW company/kw.json               # a country environment, as a file
wellbore-config samples --all starter                    # everything, in the layout of the published downloads
What In the tool In the repository
The environment template and its JSON Schema generated from the registered toolboxes: template, schema src/TheTechIdea.OilGas.Wellbore.Data/Configuration/
62 country environments embedded: countries, samples <CODE>, template --country <CODE> .../Wellbore.Data/Configuration/Countries/; published as downloads/countries/<CODE>.environment.json
Samples: environments for Norway and Kuwait, two stratigraphic lexicons, company labels, a code vocabulary, a customer CSV profile, and a README saying what each shows embedded: samples <name> src/TheTechIdea.OilGas.Wellbore.Loaders/Samples/; published as downloads/samples/
Mapping profiles csv, ppdm39, edm and template (copy it for your own schema) embedded: samples profile:<name> .../Wellbore.Loaders/Profiles/

The tool looks for no environment file by itself: every command takes the environment file as an argument, and paths inside it are relative to it. wellbore-config setup new <folder> <country> makes the first one and says what to run next; a missing environment file is reported with the command that writes a starter. A file that exists is never overwritten unless you say --overwrite.

1. Start from the country

wellbore-config countries
wellbore-config template --country NO company/environment.json

The country preset brings units, date and number formats, regulators, the tubular catalogue of the national standard (API 5CT / ISO 11960, GOST 632-80 / 633-80 ...), datums and magnetic settings. Keep only what the company changes; add "locale" and "branding" for its culture and identity.

2. Name the data sources

"dataSources": {
  "warehouse": { "kind": "companyDb", "path": "WellsProd", "profile": "ppdm39" },
  "edm":       { "kind": "edmXml", "path": "exports/edm.xml", "where": { "holeSection": { "hole_sect_group_id": "PLAN" } } },
  "wireline":  { "kind": "dlis", "path": "logs/run1.dlis" }
}

Paths are relative to the environment file. Built-in kinds are csv, excel, edmXml, las, dlis and witsml; a database is a kind the application registers (IDataSourceFactory). wellbore-config sources company/environment.json loads each source once.

3. Measure the coverage

wellbore-config coverage company/environment.json warehouse --worksheet warehouse-coverage.json

The report lists every value the source holds that the environment does not resolve - string kinds and statuses, component types, contact types, formation tops, lithologies, units, log mnemonics - with how often it occurs, a well holding it and the setting that fixes it. The worksheet lists the unresolved codes ready to fill in. Repeat after each of the next steps until the report is empty.

4. Map the code values

Copy the filled-in codes into the source: "codes": { "string": { "kind": { "SURF_CSG": "Surface" } } }. Codes used by several sources go in a vocabulary file (resources.vocabularyFiles) instead.

5. Equipment and symbols

Component types come from the model catalog: map company equipment codes to catalog types (step 4) or add the company's own types (resources.modelCatalogFiles). Each type needs a schematic symbol: resources.componentSymbolsFile maps types to symbols, and resources.symbolCatalogFile replaces the symbol catalog itself.

6. Stratigraphy

Write the company's lithostratigraphy as a lexicon file (resources.lexiconFiles): each unit with its aliases (every spelling seen in the data), local names, rank, lithology and colour - and its parent in the International Chronostratigraphic Chart, which is built in underneath (resources.standardLexicons): { "id": "UPPER_SAND", "name": "Upper Sand Formation", "rank": "Formation", "parent": "Albian" }. Chart names (Jurassic, Upper / Late Jurassic, Bajocian ...) resolve without any file. Set display.chronostratigraphyRank (for example "Epoch") to show each well's tops on their chart units beside the depth track.

7. Lithology

Lithology codes resolve against the lithology library: the built-in one (which also answers to the FGDC pattern numbers, e.g. FGDC-607 sandstone) or the company's (resources.lithologyFile), with an alias for every code its data uses.

8. Logs

Curve mnemonics that match no curve rule show in the coverage of log sources: give vendor or language variants as logs.mnemonicAliases ("ГК": "GR"), and add curve rules for families the company uses.

9. Tubulars

Schematic validation checks casing and tubing sizes, grades and connections against tubulars (from the country preset). Add the company's proprietary connections and grades so they are not reported (WS080-WS082).

10. Surveys

Survey uncertainty uses the tool models of survey (OWSG / ISCWSA built in) and the magnetic field of the well's date and place; select the company's default (survey.toolModel) and add the tool models its survey contractors deliver as ISCWSA error-model JSON files (resources.toolModelFiles; each joins survey.toolModels under its name, replacing a built-in model of the same name).

11. Verify

Turn what the company knows into checks: dataSource cases (well names, counts, curve values, "maxWarnings": 0 for full coverage), dipCorrection cases from vendor dip picks, and the reference cases of the other parts.

wellbore-config verify company/environment.json

Run it in CI; it fails when a check fails or the configuration has errors.

12. Hand over

wellbore-config save company/environment.json handover/

writes the whole configuration - environment and every part it uses - as JSON files; data files are referred to, not copied.

Checklist

Step Done when
Country wellbore-config validate has no errors
Data sources wellbore-config sources loads every source
Coverage wellbore-config coverage reports nothing to resolve for each source
Equipment no component type without a symbol (coverage area "symbols")
Stratigraphy no top outside the lexicons (coverage area "lexicon")
Lithology, logs, units coverage areas "lithology", "mnemonics", "units" are empty
Verification wellbore-config verify passes, with dataSource cases for each source
Hand-over wellbore-config save reports nothing skipped

Survey angles in other units. Inclination and azimuth are read as degrees unless the profile names a unit for them - a units column ("units": { "inclination": "angle_unit" }) or defaultUnits ("inclination": "rad"). deg, rad and gon are known; the Russian град means degrees (not gons, which is why grad is deliberately not accepted).