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" }) ordefaultUnits("inclination": "rad"). deg, rad and gon are known; the Russianградmeans degrees (not gons, which is whygradis deliberately not accepted).