Note: This Help Article applies to ECLI 2.3.0 and higher, though all but six of the parameters below have been around since ECLI 2.2.1.
ECLI has a set of parameters that accept command line arguments. ECLI arguments can be combined in various commands. In addition to passing arguments on the command line, ECLI also supports the definition of a set of attributes through a pinnacle21.conf file.
General Notes
Enclose all source path parameters in quotes so that all whitespace and special characters are interpreted correctly.
Pay special attention to OS-specific artifacts. For example, Windows uses back-slashes rather than forward-slashes, and you need to use the symbols that work for your operating system.
For example, specifying a source.sdtm directory:
on Mac : "aspera:///Users/someuser/ECLI/sdtm"
on Windows : "aspera://C:\Users\Someuser\ECLI\sdtm"
CLI Parameter Table
Help
Parameter | Valid Values | Default | Commands | Description |
--help | N/A | N/A | Other | Prints list of all error codes |
Requests
Parameter | Valid Values | Default | Commands | Description |
--api.key | P21 Enterprise API Key | None - Required | All | Key used to validate the request on the server. |
--web.host | None - Required | All | Address where the request is sent. | |
--project |
|
| All | Name of the project that contains the data to be validated. |
--study |
|
| All | Name of the study that contains the data to be validated. |
--group |
|
| All | Additional Group to assign to the Data Package. Must have Project Manager Role or greater. |
--datapackage | Data package name |
| All | Notes† |
--adapter | True, False | False | Define.xml generation | Flag specifies if an adapter is used to import a custom format. |
--create.always | True, False | True | All | Enterprise will create new project/study if it does not already exist. This parameter does not control data package creation. |
--output.format | File Format | None | Define.xml generation | Specifies output format. |
--output | CLI output options depend on the operation.* | “/reports” | Define.xml generation | Default output path for reports. |
--create.path |
| False | All | Required to make new output file paths. Else, if the path doesn't already exist, you will get an error. |
*For define spec upload and conversion this parameter specifies define.xml.
–Pair with --source.define=define-designer to export define.xml from the P21E Define Designer.
For validation, this parameter can have the following values:
–browser – CLI will open validation report in the browser after validation is completed
–<JSON file name> - path or name of the JSON file that will contain report URL.
–no value – report URL will be printed on the screen.
†Notes
If
--datapackageis specified and matches an existing Data Package, it will be used.If
--datapackageis specified but it does not match any existing Data Package, it will be created.If
--datapackageis not specified, CLI will use datapackage with a default name, which is SDTMIG for SDTM standard. If it doesn't exist, CLI will create it.
Validator - Source Data
Parameter | Valid Values | Default | Commands | Description |
--source.adam | <path>* | None | Data validation | Specifies the location of the source for ADaM data files. |
--source.sdtm | <path>* | None | Data validation | Specifies the location of the source for SDTM data files. |
--source.send | <path>* | None | Data validation | Specifies the location of the source for SEND data files. |
--source.bimo | <path>* | None | Data validation | Specifies the location of the source for BIMO data files. |
--source.define | <file>† | None | Data validation, Define.xml validation | Path to define.xml file. Uses define.xml from define designer that is associated with the data package. |
--transfer.target.rate | <number> | None | Data validation | Specifies the maximum transfer rate for uploading data via Aspera. The value in <number> is in kbps. A value of 0 indicates no limit (e.g., maximum transfer rate). |
*Can contain directories or individual files separated by semicolon. Provided paths can include any supported source data formats, define.xml, stylesheets, programs, and other related validation files. Files from subfolders would be included in the validation.
Examples for --source.adam:
--source.adam=aspera://c:\mydata
--source.adam=aspera://data.zip
--source.adam=aspera://./data/
†If you omit this parameter, our default is search the source folder for define.xml anyway.
If you want a specific define.xml file, include the full filename:
--source.define="aspera://.\SendStudy001\define.xml" ^
If you have already called Aspera for your datasets, you do not need to call Aspera again for your define. E.g., this command calls Aspera only once:
--source.send="aspera://.\SendStudy001\" ^
--source.define=".\SendStudy001\define.xml" ^
Validator - Source Format
Parameter | Valid Values | Default | Commands | Description |
--source.encoding | <encoding> | None | Data validation | Encoding used for source. |
--source.qrs | <path> | None | Data validation | Path to source QRS data files. Can contain directories or individual files separated by semicolon. |
Standard and Config
Parameter | Valid Values | Default | Commands | Description |
--standard | SDTM SDTMIG | None - Required | All | Specifies which standard to validate against. |
--list.config | N/A | None | Other | Writes Project, Study, or Data Package configuration to a file path provided in --output |
--engine.version | <version> | P21 | All | E..g, "P21 2204.0". Specifies which version of the engine to use to validate. |
--standard.version | <version> | None - Required | All | Specifies which version of the standard to validate against. |
--define.standard | 2.0 2.1 | 2.0 | All | Version of Define standard |
Validator - Terminology
Parameter | Valid Values | Default | Commands | Description |
--cdisc.ct.adam.version | <version> | <latest> | All | Version of ADaM CDISC controlled terminology. |
--cdisc.ct.sdtm.version | <version> | <latest> | All | Version of SDTM CDISC controlled terminology. |
--cdisc.ct.send.version | <version> | <latest> | All | Version of SEND CDISC controlled terminology. |
--meddra.version | <version> | <latest> | All | Version of MedDRA dictionary. |
--ndf-rt.version | <version>, "latest"* | <latest> | All | Version of NDF-RT/MED-RT dictionary. |
--snomed.version | <version>, "latest" | <latest> | All | Version of SNOMED dictionary. |
--unii.version | <version>, "latest" | <latest> | All | Version of UNII dictionary. |
--whodrug.version | <version> | None | All | Version of WHODrug dictionary. |
--loinc.version | <version>, "latest" | None | All | Version of LOINC dictionary. |
*Four dictionaries can be set to always update and run the latest version with the value "latest".
Validator - Report
Parameter | Valid Values | Default | Commands | Description |
--report | <file> | None | Data validation, Define.xml validation | Path and file name to where the report will be saved. |
--report.cutoff | <#> | 1000 | Data validation, Define.xml validation | Number of times a record detail is printed per issue. For no limit specify 0. |
--source.comment | <string> | None | Data validation | Validation comment or note, up to 255 characters. Will appear on the validation history in the UI. |
Define.xml Designer - Generate Define.xml
Parameter | Valid Values | Default | Commands | Description |
--source | <file> | None - Required | Define.xml generation, Define.xml validation | Path to Excel specification. |
--import.validation.metadata | None | None | Define.xml generation | Use latest validation as source for define.xml generation. |
--create.value.level.for | SEND/SDTM: | None | Define.xml generation | Create VLM for the variables specified. |
--automerge | None | None | Define.xml generation | Merge the latest validation into the metadata in P21E. |
--output | <file> | None - Required | Define.xml/xlsx/pdf generation | Path to define.xml/xlsx/pdf file. |
--output.format | xlsx, xlsx-by-dataset, pdf, xml | None | Define.xml generation | Specifies output format. |
Other Parameters
Parameter | Valid Values | Default | Commands | Description |
--ascp.file | <file path> | None | Data validation | File path to the Aspera ‘ascp’ binary. Allows the user to replace the copy of ascp bundled with the ECLI. |
--local.temp.folder | <file path> | None | Data validaiton | Run ECLI with a local temp folder. |
--clean | True, False | False | All | Clean all output before the command is executed. |
Error Codes
When the ECLI encounters an error, it will return one of these error codes to help with troubleshooting. (Exit codes are no longer returned, as of ECLI 2.2.1 and higher.)
Custom CT Support
The CLI supports custom CT as input to --cdisc.ct.[standard].version parameter.
The CLI will look for the custom CT on the enterprise server with a matching custom CT name.
Output Options
The available CLI output options depend on which operation is being executed. For define spec upload and conversion, output is always the path to export the specified define.xml file, its Excel spec or PDF file. The file format (XML/XLSX/PDF) is determined either from the file extension provided in --output parameter or from the --output.format parameter value.
For validation, the output parameter can have the following values:
Browser – the CLI will open validation report in the browser after validation is completed
<JSON file name> - path or name of the JSON file that will contain report URL.
No value – report URL will be printed on the screen.
👣 What's Next?
Learn more in How do I use P21 Enterprise via API/CLI?
Email questions or feedback to support@pinnacle21.atlassian.net.