GISB Connector

Version 22.0.8473


GISB Connector


GISB Connectors support sending and receiving messages via the GISB protocol.

Overview

A GISB connection is configured in two places. The Trading Partner Info section of each GISB connector should be configured with the connection settings specific to a single trading partner, and the Alternate Local Profile section should be configured with a local identifier and a personal key. When an input file is processed by an GISB connector, it is packaged and sent to the specified trading partner.

When CData Arc receives a file over GISB, it attempts to route the file to a specific GISB connector. The application uses the GISB identifiers in the message to determine which GISB connector should receive the file. When a file is routed to a GISB connector, that file is placed in the connector’s Receive directory, or is passed along to the next connected connector in the flow.

Connector Configuration

This section contains all of the configurable connector properties.

Settings Tab

Trading Partner Info

Settings for identifying and connecting to a specific trading partner.

  • Connector Id The static name of the connector. All connector-specific files are held in a folder by the same name within the Data Directory.
  • Connector Description An optional field to provide free-form description of the connector and its role in the flow.
  • GISB Identifier The identifier specific to the target trading partner. This value is included in outgoing messages, and it is also used to route incoming messages to the appropriate GISB connector.
  • Partner URL The trading partner’s public endpoint where outgoing messages should be sent.
  • GISB Version The protocol version of the GISB client.

Connection Info

Settings related connection parameters for the specified trading partner.

  • Send Message Security Whether to sign and/or encrypt outgoing messages. Signatures and encryption are strongly recommended.
  • Receive Message Security Whether to require that signatures and encryption are present for incoming messages. An error will be thrown if a received message does not have a required security parameter.
  • Client Timeout The length of time the connector will wait for a connection response before throwing a timeout error.

Receipts

Settings related to sending and requesting message receipts.

  • Security Whether the Receipt should include a signature block verifying the message integrity and identity of the recipient.

Trading Partner Keys/Certificates

Settings related to the public certificates provided by the trading partner.

  • Recipient Key Certificate The public key used for encryption and signature verification. Keys can be imported via the Import Key button, then selected from the dropdown menu.
  • SSL Server Certificate The public certificate used to verify the identity of an SSL/TLS server. Only necessary if the partner’s system requires HTTPS (rather than HTTP). If the trading partner does not provide an SSL server certificate, this setting can be left blank, to allow the underlying OS/JVM to perform certificate validation, or it can be set to ‘Any Certificate’ to unconditionally trust the target server’s identity.

Automation Tab

Automation Settings

Settings related to the automatic processing of files by the connector.

  • Send Whether files arriving at the connector will automatically be sent as GISB messages.
  • Retry Interval The amount of time before a failed send is retried. A retry is triggered when the server does not respond to a send attempt, or responds negatively to communicate that the file was not received.
  • Max Attempts The maximum number of times the connector will process the input file. Success is based on a successful server acknowledgement and validation of the receipt (when requested synchronously). If this is set to 0, the connector will retry the file indefinitely.

Advanced Tab

Alternate Local Profile

Settings that override the GISB configuration in the Profile page for this specific GISB connector. Setting an alternate local profile allows the use of different local keys and identifiers for certain trading partners.

  • Local GISB Identifier Your GISB identifier. Overrides GISB Identifier in the Profile section.
  • Secret Key The key that will be used to decrypt incoming messages and sign outgoing messages. Overrides Private Key in the Profile sections.
  • Passphrase The password required to access the local secret key.

SSL Client Authentication

Settings related to client authentication when two-way SSL authentication is required.

  • Private Certificate The private certificate presented during SSL client authentication.
  • Certificate Password The password required to access the SSL client certificate.

HTTP Authentication

Settings related to HTTP client authentication.

  • Use HTTP Authentication Whether client HTTP Authentication is enabled.
  • HTTP Authentication Type Whether to provide HTTP authentication credentials in an encrypted format (Digest) or in plain text (Basic). Basic authentication should only be used if the the connection is an HTTPS connection (rather than HTTP).
  • User The User credential for HTTP client authentication.
  • Password The Password credential for HTTP client authentication.

Custom Headers

An arbitrary set of custom headers to be included as part of the outgoing message.

Performance

Settings related to the allocation of resources to the connector.

  • Max Workers The maximum number of worker threads that will be consumed from the threadpool to process files on this connector. If set, overrides the default setting from the Profile tab.
  • Max Files The maximum number of files that will be processed by the connector each time worker threads are assigned to the connector. If set, overrides the default setting from the Profile tab.

Other Settings

Settings not included in the previous categories.

  • Signing Algorithm The algorithm to use when signing outgoing messages.
  • Encryption Algorithm The algorithm to use when encrypting outgoing messages.
  • Compression Method The algorithm to use when compressing outgoing payloads.
  • Use Temp File If enabled, the connector write data to process in a temp file, then move the temp file into processing once it has been fully written.
  • Combine Sign and Encrypt If enabled, the connector will perform both signing and encryption in the same step.
  • Send Filter A glob pattern filter to determine which files in the Send folder will be sent by the connector (e.g. *.txt). Negative patterns may be used to indicate files that should not be processed by the connector (e.g. -*.tmp). Multiple patterns may be separated by commas, with later filters taking priority except when an exact match is found.
  • Extension Map A set of name-value pairs that maps file extensions to the desired HTTP Content-Type header value. By default, the application will map the following file extensions to content types:
    .xml -> application/xml
    .edi or .x12 -> application/edi-x12
    .edifact -> application/edifact.
    All other file extensions are sent with an application/octet-stream content type. To add or overwrite mappings, this setting should be a comma-delimited list in extension=contenttype syntax (e.g. .txt=text/plain,.edi=application/edifact). Log Level The verbosity of logs generated by the connector. When requesting support, it is recommended to set this value to Debug.
  • Log Requests Whether the payload and request logs should be written when sending messages. This increases the disk space consumed when sending large messages. When requesting support, it is recommended to include requests in the debug logs and provide these along with the support request.
  • Parent Connector The connector from which settings should be inherited, unless explicitly overwritten within the existing connector configuration. Must be set to a connector of the same type as the current connector.
  • Log Messages Whether logs from processed files will include a copy of the file itself.
  • Save to Sent Folder Whether files processed by the connector should be copied to the Sent folder for the connector.
  • SSL Enabled Protocols The list of SSL/TLS protocols supported when establishing outgoing connections. It is strongly recommended to only use TLS protocols. Some obsolete operating systems do not support TLS 1.2.

Miscellaneous

Settings for specific use cases.

  • Other Settings Allows configuration of hidden connector settings in a semicolon-separated list, like setting1=value1;setting2=value2. Normal connector use cases and functionality should not require use of these settings.

Partner Setup

Trading partners must share some of the connection details that are required when configuring a new GISB connector. At a minimum, these details should include:

  • GISB Identifier
  • Partner URL
  • Partner Public Key

Send and Receive Files

After the GISB profile and partner-specific GISB connectors have been configured, files can be securely sent and received.

Send Files

Within an GISB connector, the Input tab displays the files that should be sent to the target trading partner. If Send Automation is enabled, files that reach the Input/Send Folder of the connector will automatically be packaged and sent. Successful transmissions are indicated by a green ‘Sent’ status, while warning and error statuses are represented in yellow and red. The log files for failing or successful transmissions can be accessed by expanding the row associated with the transmitted file.

The Create Test Files button can be used to generate a simple series of test files to send to the trading partner.

Receive Files

Within an GISB connector, the Output tab displays the files that have been received by the application and routed to the connector (based on the GISB identifiers present in the incoming GISB message). Each file row can be expanded to display a list of available logs for the transmission.

These files are available in the Output/Receive Folder of the connector. If the connector is connected to other connectors in the flow, files will automatically be moved from the Output/Receive Folder of the GISB connector to the Send directory of the next connector in the flow.