Command Line Options - EcoSys - Customization & Programming - Hexagon

EcoSys Gateway Web Service API Client

Language
English
Product
EcoSys
Search by Category
Customization & Programming
EcoSys Version
9.1

Authentication

Specify the EcoSys Gateway application username and password to login via the API. These credentials are required if you are not including them in the API URL (see the general API documentation for details):

-u {username} -p {password}

Encrypted Passwords

You can optionally use the encrypted format of a password. It is recommended that you enclose the value in quotations, so it is not altered by the calling shell.

Example

-u {username} -p "CIPHERTEXT{vnOcVfeXUxE=}"

Use the online utility within the EcoSys GATEWAY web UI to encrypt the password value, available under System Admin > System Utilities > Encrypt Password. In this case, the "{ }" braces are to be included in the syntax.

Alternate Syntax for Credentials: You can use the alternate syntax for authentication parameters. This is a work around to resolve issues related to the default configuration of some application servers, such as WebLogic (see related section in the general API documentation for more details).

The alternate syntax involves including the credentials as part of the REST XML API URL:

http://.../ecosys/restxml/Sample/?_username={username}&_password={password}

With this syntax, the -p and -u options can be omitted from the command line. While using the encrypted password format, you must URL-encode the password value, replacing "+" with "%2B", and "=" with "%3D" if they appear in the encrypted password value.

Runtime Parameters

Specify values for runtime parameters defined for the API in question. Repeat this option for each parameter to include. You may also specify runtime parameter values as part of the API URL (see the general API documentation for details):

-param {param1Name}={param1Value} -param {param2Name}={param2Value} ...

Logging

Specify the filename of where to write the log, as well as the level of logging detail desired.

-log {log filename}

-perfout {server metrics log filename}

-detail {count|fail|all} (applies to object writes only)

-debug {perf,xml}

The settings which apply to object writes only (not reads or event triggers), should be one of the following:

  • count — (default) log only the counts of records and success/fail, nothing about individual records

  • fail — log the counts and details about any record that got a failure code

  • all — log an entry for every record processed, including success/failure and any failure codes (most verbose)

Debug options is a comma-separated list of debug options, including:

  • perf — log a detailed performance profile report of EcoSys Gateway steps and components (client side)

  • xml — log all inbound and outbound XML to be written to the log, used for troubleshooting only

Automatic Escaping and Unescaping of Delimiters

By default, any literal delimiter characters, such as tab, newline, and backslash, will be escaped using the mappings below on output to a file. Similarly, on input from a file, the mappings will be applied to the data in the file in reverse, unescaping each field value.

  • Tab character (ASCII 8)   ↔   \t

  • Line break characters (ASCII 10 and 13)   ↔   \n

  • Backslash character (ASCII 92)   ↔   \\

To disable this automatic translation (enabled by default), apply the -escapedelims false option. NOTE, however, that this renders the output file potentially no longer parseable since the original field and line breaks are not identifiable.

Timeout for Web Service Calls

The requests made to the EcoSys server by Gateway use HTTP or HTTPS, and by default they use the system default timeout value for these calls, typically 60 seconds. If you are calling an API that takes longer to process, you may increase this timeout using this option:

-timeout {timeout seconds}

Setting the value to 0 (zero) disables the client-side timeout, and Gateway will wait indefinitely on the server to complete the request.

The requests to an event trigger API will continue to run on the server even after a client-side timeout has been reached, so setting this option to a low value, such as 5 seconds, and ignoring the timeout message can effectively make an asynchronous call to the event trigger API.

Tuning the Message Size

For object writes (not reads or event triggers), EcoSys Gateway will send records to the API in messages, breaking up large files into multiple messages as necessary. Some systems are more efficient or less efficient with larger or smaller message sizes. You can override the default message size (number of records per message) using this option:

-msgsize {records-per-message}

The best performance is achieved using message sizes between 100 and 3000, but it will depend on several factors such as

  • Number of attributes defined per record

  • Configuration of the specific published API

  • Resources and configuration of the server and database infrastructure.

If performance is a key consideration, it is recommended to benchmark the system's throughput using different message sizes to find the optimal setting. The default message size is 500 (If not specified).

Test Mode (Generate Data)

EcoSys Gateway can generate randomized data instead of reading data from a file. In this mode, only first two lines of the input file are read: the header, and a template data row. The template is used to generate records up to the number specified. For more information, see Test Data Generation Mode.

-test {record-count}

Paging option for REST APIs

EcoSys REST API supports a paging option for the GET (read) method. When the paging option is set, the number of rows specified will be returned and a link to the next page will be included in the response except for the last page.

Since paging option requests returning a large set of data in smaller chunks, it reduces the load and memory usage of the system.

To specify the pageSize, use the following option:

- pageSize {number of objects to a page, default=1000}

Gateway will make the API call using the specified page size and return all objects into an output file by automatically retrieving the next page until there are no more pages to retrieve.