Gzip Pipeline Component
The GZIP pipeline component implements a gzip compressor and decompressor, compliant to RFC 1952 and compatible with the UNIX gzip and gunzip utilities.
Remarks
The GZIP pipeline component is used when generating BizTalk Pipelines for sending and receiving messages which are desired to be zipped or unzipped using gzip compression.
GZIP Assembler/Encoder Pipeline Component
The Assembler/Encoder takes a group of messages as input which contains raw data, and generates a GZIP archive message as output.
Compression strength is regulated by the CompressionLevel property.
GZIP Disassembler/Decoder Pipeline Component
The Disassembler/Decoder takes a zipped message as input, and generates a group of unzipped messages as output.
Please refer to the section on adapter configuration for a description of how to configure receive locations and send ports for this adapter.
Assembler Property List
The following is the full list of the properties of the assembler Pipeline Component with short descriptions. Click on the links for further details.
| ArchiveFileName | The name of the gzip archive. |
| CompressionLevel | The compression level to use. |
| FileCompressedName | Filename, as stored inside of the archive. |
| Other | Defines a set of configuration settings to be used by the pipeline component. |
| RuntimeLicense | Specifies the component runtime license key. |
| TempPath | A temporary directory where uncompressed and compressed data can be stored. |
| TransportLog | Tells the component where and how to report information about its operations. |
Disassembler Property List
The following is the full list of the properties of the disassembler Pipeline Component with short descriptions. Click on the links for further details.
| Other | Defines a set of configuration settings to be used by the pipeline component. |
| RuntimeLicense | Specifies the component runtime license key. |
| TempPath | A temporary directory where uncompressed and compressed data can be stored. |
| TransportLog | Tells the component where and how to report information about its operations. |
Encoder Property List
The following is the full list of the properties of the encoder Pipeline Component with short descriptions. Click on the links for further details.
| ArchiveFileName | The name of the gzip archive. |
| CompressionLevel | The compression level to use. |
| FileCompressedName | Filename, as stored inside of the archive. |
| Other | Defines a set of configuration settings to be used by the pipeline component. |
| RuntimeLicense | Specifies the component runtime license key. |
| TempPath | A temporary directory where uncompressed and compressed data can be stored. |
| TransportLog | Tells the component where and how to report information about its operations. |
Decoder Property List
The following is the full list of the properties of the decoder Pipeline Component with short descriptions. Click on the links for further details.
| Other | Defines a set of configuration settings to be used by the pipeline component. |
| RuntimeLicense | Specifies the component runtime license key. |
| TempPath | A temporary directory where uncompressed and compressed data can be stored. |
| TransportLog | Tells the component where and how to report information about its operations. |
Config Settings
The following is a list of config settings for the Pipeline Component with short descriptions. Click on the links for further details.
| PipelineOptions | Options defining the validation and protection functionality of the pipeline component. |
| SuggestCompressedName | Whether to suggest a file name. |
ArchiveFileName Property (Gzip Pipeline component)
The name of the gzip archive.
Data Type
String
Default Value
""
Remarks
If specified this determines the name of the archive created by the adapter.
This property is not available in the Disassembler/Decoder.
CompressionLevel Property (Gzip Pipeline component)
The compression level to use.
Data Type
Integer
Default Value
4
Remarks
This property specifies the level of compression to be used, between 1 and 6. Higher values will cause the pipeline component to compress better; lower values will cause the pipeline component to compress faster.
Storing without compression is not supported for Gzip.
This property is not available in the Disassembler/Decoder.
FileCompressedName Property (Gzip Pipeline component)
Filename, as stored inside of the archive.
Data Type
String
Default Value
""
Remarks
FileCompressedName contains the name of the compressed file, as stored within the gzip header.
This field should generally be set with a relative path or with no path at all. The exact interpretation of the path is left to the decompression software; generally, pathnames will be interpreted as relative to a base directory, and these subdirectories will be created as needed. Absolute pathnames will not be interpreted correctly by the adapter, and may or may not be interpreted correctly by other decompression software.
Paths should be specified in standard (UNIX) format. They may also be specified in the format native to the host operating system, in which case they will be immediately converted.
It is not usually necessary to manually set the value of this property; it will be assigned by the adapter when compressing if it is not specified.
This property is not available in the Disassembler/Decoder.
Other Property (Gzip Pipeline component)
Defines a set of configuration settings to be used by the pipeline component.
Data Type
String
Default Value
""
Remarks
The pipeline component accepts one or more configuration settings. These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the pipeline component, access to these internal properties is provided through the Other property.
The Other property may be set to one or more configuration settings (name/value pairs). Set one setting per line.
For example:
configname1=value1
configname2=value2
RuntimeLicense Property (Gzip Pipeline component)
Specifies the component runtime license key.
Data Type
String
Default Value
""
Remarks
You can use the RuntimeLicense property to set the runtime key for the adapter license.
This property may be configured on the adapter's static handler property page in the BizTalk Server administration console.
TempPath Property (Gzip Pipeline component)
A temporary directory where uncompressed and compressed data can be stored.
Data Type
String
Default Value
""
Remarks
This property indicates a temporary directory where the pipeline component can store any data before the pipeline component processes it. If TempPath is empty, the pipeline component will receive all data to memory. If set, the pipeline component will generate and write all inbound data to a temporary file in the specified directory.
Once the file is submitted to BizTalk, the pipeline component will handle closing the file stream and deleting the temporary file. However, if the pipeline component is shut down during a transfer some temporary files may be left in the directory. To ensure optimal performance, server administrators should check the directory regularly and remove old or extraneous files.
This property accepts the "%TEMP%" macro, which will be replaced with the default system temporary directory at runtime.
Note: by default, this property is empty and the pipeline component will use memory streams to store all inbound data before submitting it to BizTalk. It is recommended that you use a temporary directory when downloading large batches or batches containing large files to alleviate potential increased memory requirements.
TransportLog Property (Gzip Pipeline component)
Tells the component where and how to report information about its operations.
Data Type
LogRemarks
This is a Log type property which contains fields describing how and where the adapter will record information about its execution.
This property may be configured on the adapter's static handler property page in the BizTalk Server administration console.
Certificate Type
The digital certificate being used.
Remarks
This type describes the current digital certificate. The certificate may be a public or private key. The fields are used to identify or select certificates.
Fields
Store
String
Default Value: "MY"
The name of the certificate store for the client certificate.
The StoreType field specifies the type of the certificate store specified by Store. If the store is password protected, specify the password in StorePassword.
Store is used in conjunction with the Subject field in order to specify client certificates. If Store has a value, and Subject is set, a search for a certificate is initiated. Please refer to the Subject field for details.
Designations of certificate stores are platform-dependent.
The following are designations of the most common User and Machine certificate stores in Windows:
| MY | A certificate store holding personal certificates with their associated private keys. |
| CA | Certifying authority certificates. |
| ROOT | Root certificates. |
| SPC | Software publisher certificates. |
In Java, the certificate store normally is a file containing certificates and optional private keys.
When the certificate store type is PFXFile, this property must be set to the name of the file. When the type is PFXBlob, the property must be set to the binary contents of a PFX file (i.e. PKCS12 certificate store).
If the provider is OpenSSL, the certificate store is a file containing a certificate and a private key. This property must be set to the name of the file.
StorePassword
String
Default Value: ""
If the certificate store is of a type that requires a password, this property is used to specify that password in order to open the certificate store.
StoreType
CertStoreTypes
Default Value: 0
The type of certificate store for this certificate.
The adapter supports both public and private keys in a variety of formats. When the cstAuto value is used, the adapter will automatically determine the type. This field can take one of the following values:
| 0 (cstUser - default) | For Windows, this specifies that the certificate store is a certificate store owned by the current user.
Note: This store type is not available in Java. |
| 1 (cstMachine) | For Windows, this specifies that the certificate store is a machine store.
Note: This store type is not available in Java. |
| 2 (cstPFXFile) | The certificate store is the name of a PFX (PKCS#12) file containing certificates. |
| 3 (cstPFXBlob) | The certificate store is a string (binary or Base64-encoded) representing a certificate store in PFX (PKCS#12) format. |
| 4 (cstJKSFile) | The certificate store is the name of a Java Key Store (JKS) file containing certificates.
Note: This store type is only available in Java. |
| 5 (cstJKSBlob) | The certificate store is a string (binary or Base64-encoded) representing a certificate store in Java Key Store (JKS) format.
Note: this store type is only available in Java. |
| 6 (cstPEMKeyFile) | The certificate store is the name of a PEM-encoded file that contains a private key and an optional certificate. |
| 7 (cstPEMKeyBlob) | The certificate store is a string (binary or Base64-encoded) that contains a private key and an optional certificate. |
| 8 (cstPublicKeyFile) | The certificate store is the name of a file that contains a PEM- or DER-encoded public key certificate. |
| 9 (cstPublicKeyBlob) | The certificate store is a string (binary or Base64-encoded) that contains a PEM- or DER-encoded public key certificate. |
| 10 (cstSSHPublicKeyBlob) | The certificate store is a string (binary or Base64-encoded) that contains an SSH-style public key. |
| 11 (cstP7BFile) | The certificate store is the name of a PKCS#7 file containing certificates. |
| 12 (cstP7BBlob) | The certificate store is a string (binary) representing a certificate store in PKCS#7 format. |
| 13 (cstSSHPublicKeyFile) | The certificate store is the name of a file that contains an SSH-style public key. |
| 14 (cstPPKFile) | The certificate store is the name of a file that contains a PPK (PuTTY Private Key). |
| 15 (cstPPKBlob) | The certificate store is a string (binary) that contains a PPK (PuTTY Private Key). |
| 16 (cstXMLFile) | The certificate store is the name of a file that contains a certificate in XML format. |
| 17 (cstXMLBlob) | The certificate store is a string that contains a certificate in XML format. |
| 18 (cstJWKFile) | The certificate store is the name of a file that contains a JWK (JSON Web Key). |
| 19 (cstJWKBlob) | The certificate store is a string that contains a JWK (JSON Web Key). |
| 21 (cstBCFKSFile) | The certificate store is the name of a file that contains a BCFKS (Bouncy Castle FIPS Key Store).
Note: This store type is only available in Java and .NET. |
| 22 (cstBCFKSBlob) | The certificate store is a string (binary or Base64-encoded) representing a certificate store in BCFKS (Bouncy Castle FIPS Key Store) format.
Note: This store type is only available in Java and .NET. |
| 23 (cstPKCS11) | The certificate is present on a physical security key accessible via a PKCS#11 interface.
To use a security key, the necessary data must first be collected using the CERTMGR adapter. The ListStoreCertificates method may be called after setting CertStoreType to cstPKCS11, CertStorePassword to the PIN, and CertStore to the full path of the PKCS#11 DLL. The certificate information returned in the CertList event's CertEncoded parameter may be saved for later use. When using a certificate, pass the previously saved security key information as the Store and set StorePassword to the PIN. Code Example. SSH Authentication with Security Key:
|
| 99 (cstAuto) | The store type is automatically detected from the input data. This setting may be used with both public and private keys and can detect any of the supported formats automatically. |
Subject
String
Default Value: ""
The subject of the certificate used for client authentication.
When this property is set, a search is performed in the current certificate store certificate with matching subject.
If an exact match is not found, the store is searched for subjects containing the value of the property.
When setting the property to a partial subject, CN= should be omitted. For example, the following code would find the certificate with subject CN=Test Certificate, OU=People, C=US
Example (Searching with partial subject)
Control.CertSubject = "Test"
If a match is not found, the property is set to an empty string, and no certificate is selected.
The special value "*" picks a random certificate in the certificate store.
If a matching certificate is found, Subject is set to the full subject of the matching certificate.
Thumbprint
String (read-only)
Default Value: ""
The thumbprint of the certificate.
This field is used to specify the thumbprint of the certificate. When there are multiple certificates in the store that have the same subject, the thumbprint will be used to distinguish between them.
Constructors
Constructors are only relevant when configuring adapters in orchestrations.
public Certificate();
Creates a Certificate instance whose properties can be set.
public Certificate(string certificateFile);
Opens CertificateFile and reads out the contents as an X509 public key.
public Certificate(byte[] certificateData);
Parses CertificateData as an X509 public key.
public Certificate(CertStoreTypes certStoreType, string store, string storePassword, string subject);
CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. Store is a file containing the certificate store. StorePassword is the password used to protect the store. After the store has been successfully opened, the constructor will attempt to find the certificate identified by Subject . This can be either a complete or a substring match of the X509 certificate's subject Distinguished Name (DN).
public Certificate(CertStoreTypes certStoreType, string store, string storePassword, byte[] encoded);
CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. Store is a file containing the certificate store. StorePassword is the password used to protect the store. After the store has been successfully opened, the constructor will load Encoded as an X509 certificate and search the opened store for a corresponding private key.
public Certificate(CertStoreTypes certStoreType, byte[] storeBlob, string storePassword, string subject);
CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. Store is a string (binary- or base64-encoded) containing the certificate store. StorePassword is the password used to protect the store. After the store has been successfully opened, the constructor will attempt to find the certificate identified by Subject . This can be either a complete or a substring match of the X509 certificate's subject Distinguished Name (DN).
public Certificate(CertStoreTypes certStoreType, byte[] storeBlob, string storePassword, byte[] encoded);
CertStoreType identifies the type of certificate store to use. See StoreType for descriptions of the different certificate stores. Store is a string (binary- or base64-encoded) containing the certificate store. StorePassword is the password used to protect the store. After the store has been successfully opened, the constructor will load Encoded as an X509 certificate and search the opened store for a corresponding private key.
Firewall Type
The firewall the component will connect through.
Remarks
When connecting through a firewall, this type is used to specify different properties of the firewall such as the firewall Host and the FirewallType.
Fields
AutoDetect
Boolean
Default Value: False
Tells the adapter whether or not to automatically detect and use firewall system settings, if available.
FirewallType
FirewallTypes
Default Value: 0
Determines the type of firewall to connect through. The applicable values are the following:
Host
String
Default Value: ""
Name or IP address of firewall (optional). If a Host is given, requested connections will be authenticated through the specified firewall when connecting.
If the Host field is set to a Domain Name, a DNS request is initiated. Upon successful termination of the request, the Host field is set to the corresponding address. If the search is not successful, an error is returned.
Password
String
Default Value: ""
A password if authentication is to be used when connecting through the firewall. If Host is specified, the User and Password fields are used to connect and authenticate to the given firewall. If the authentication fails, a trappable error is fired.
Port
Integer
Default Value: 0
The TCP port for the firewall Host. See the description of the Host field for details.
Note that the Port is set automatically when FirewallType is set to a valid value. See the description of the FirewallType field for details.
User
String
Default Value: ""
A user name if authentication is to be used connecting through a firewall. If the Host is specified, the User and Password fields are used to connect and authenticate to the given Firewall. If the authentication fails, a trappable error is fired.
Constructors
Constructors are only relevant when configuring adapters in orchestrations.
public Firewall();
Log Type
A log where the component will record information about its operations.
Remarks
This describes how and where the adapter will record information describing its execution.
Fields
Location
String
Default Value: "Application"
This field describes the location where the logging information is to be written.
If the EventLog LogType has been chosen, this field must contain the name of the Event Log to which the information should be written. The default value for this field is "Application". If a value other than "Application" is set the computer must be restarted for the change to take effect. Note that the same event log must be used for all send ports and receive locations that use the same adapter.
If the File LogType has been chosen, this field must contain the location of the file to write logging information to on the file system.
The adapter also supports logging to files based on the current date and time. This allows for log files to be organized by days, months, or other intervals as specified. When specifying a log filename include a valid .NET date and time format string within the < and > characters. For instance C:\logs\sftp_<yyyyMMdd>.log or C:\logs\as2_<yyyyMMdd>T<hhmm>.log.
LogMode
LogModes
Default Value: 3
This field controls what information the adapter logs. The possible values have the following affect on the adapter's behavior:
| Verbose | The adapter will report all information regarding the transport. |
| Info | The adapter will report all major operations, as well as all warnings and errors. |
| Warning | The adapter will report any conditions that could result in unpredictable behavior as well as errors. |
| Error | The adapter will report all errors that prevent normal operations from completing. |
| Fatal | The adapter will report only serious errors that cause the adapter to completely stop functioning. |
LogType
LogTypes
Default Value: 1
This property controls where the adapter will log the information. The possible values have the following affect on the adapter's behavior:
| None | The adapter will not report any logging information. |
| EventLog | The adapter will report all logging information to the event log. The specific event log must be defined in the Location field when this type is selected. |
| File | The adapter will report all logging information to a file. The desired file must be specified in the Location field when this type has been selected. |
Constructors
Constructors are only relevant when configuring adapters in orchestrations.
public Log();
public Log(LogTypes logType, string location, LogModes logMode);
OAuthAuthorizationParam Type
This type holds details of the OAuth authorization.
Remarks
This type holds details of the OAuth authorization.
Fields
AuthorizationScopes
String
Default Value: ""
A space separated list of scopes as defined by the authorization server.
AuthorizationString
String
Default Value: ""
The OAuth Authorization string. This field holds the current OAuth authorization string. This is retrieved during the OAuth authorization process and is used to authenticate the request. This is a string like:
Bearer ya29.AHES6ZSZEJzATdZYjeihDn5W-VrXSsxEZu5p0pclxGdKKQ
CacheLocation
String
Default Value: ""
The location on disk of the OAuth Cache File.
This field specifies the location on disk of the OAuth cache file. This file holds OAuth credentials that may be automatically used during runtime and by other ports using the same provider. The adapter uses the data within the cache file to automatically refresh expired tokens at runtime. Do not alter the contents of the file directly.
One file for each provider is used by default. For instance for Box the value is:
%APPDATA%\nsoftware\CloudStorage BizTalk Adapter\BoxOAuthCache.txt
This value may be specified manually as well.
CallbackURL
String
Default Value: ""
The Callback URL used during OAuth authorization.
This field specifies the local URL to which the browser is redirected when initially performing authorization. When initially establishing Authorization set this value to the redirect URI that is registered for your application with the service provider. For instance "http://localhost:7777".
The adapter will parse this URL and start a small embedded web server on the specified port to receive the OAuth response from the provider during OAuth authorization.
This value is required to perform OAuth authorization.
ClientId
String
Default Value: ""
The id of the client assigned when registering the application.
This field holds the id of the client that was assigned when initially registering the application.
This value is required to perform OAuth authorization.
ClientSecret
String
Default Value: ""
The secret of the client assigned when registering the application.
This field holds the secret of the client that was assigned when initially registering the application.
This value is required to perform OAuth authorization.
ExpiresIn
Integer
Default Value: 0
The expiration time of the current OAuth authorization string.
This value is populated after OAuth authorization and holds the expiration time of the OAuth access token as reported by the service provider. This is used at runtime to calculate whether the token should be refreshed before attempting an operation. If the token is expired the adapter will automatically refresh the token. If the token is not expired the adapter will use the current token.
This value should not be set manually.
Note: Not all providers provide this value. For instance Dropbox access tokens never expire.
RefreshToken
String
Default Value: ""
The refresh token received from or sent to the authorization server.
This field holds the refresh token received during the initial OAuth authorization. It is used by the adapter to automatically request a new AuthorizationString when the current value expires.
ServerAuthURL
String
Default Value: ""
The URL of the authorization server.
ServerTokenURL
String
Default Value: ""
The URL of the token server.
ServiceProvider
String
Default Value: ""
The service provider to authenticate with.
This field defines the service provider. This is used when performing OAuth authorization. OAuth authorization is only applicable to some providers. If the provider does not support OAuth a warning will be displayed. Possible values when using the Cloud Storage adapter are:
- Amazon S3
- Azure Blob
- Azure File
- Backblaze B2
- Box.com
- Digital Ocean Spaces
- Dropbox
- Google Cloud Storage
- Google Drive
- Hadoop DFS
- IBM Cloud Object Storage
- Linode Object Storage
- Microsoft OneDrive
- Wasabi
- Gmail
- Other
TimeStamp
String
Default Value: "0"
The timestamp of the OAuth authorization string.
This field holds the timestamp of when the AuthorizationString was retrieved. This is used in conjunction with ExpiresIn to calculate if refreshing the token is required. For more details see ExpiresIn.
This value should not be set manually.
Constructors
Constructors are only relevant when configuring adapters in orchestrations.
public OAuthAuthorizationParam();
Proxy Type
The proxy the component will connect to.
Remarks
When connecting through a proxy, this type is used to specify different properties of the proxy such as the Server and the AuthScheme.
Fields
AuthScheme
ProxyAuthSchemes
Default Value: 0
Use the AuthScheme field to tell the adapter which type of authorization to perform when connecting to the proxy. This is only used when the User and Password fields are set.
AuthScheme should be set to authNone (3) when no authentication is expected.
By default, AuthScheme is authBasic (0), and if the User and Password fields are set, the component will attempt basic authentication. If AuthScheme is set to authDigest (1), digest authentication will be attempted instead.
If AuthScheme is set to authProprietary (2), then the authorization token will not be generated by the adapter. Look at the configuration file for the adapter being used to find more information about manually setting this token.
If AuthScheme is set to authNtlm (4), NTLM authentication will be used. This option is only available in the SSL package.
For security reasons, setting this property will clear the values of User and Password.
AutoDetect
Boolean
Default Value: False
Tells the adapter whether or not to automatically detect and use proxy system settings, if available.
Password
String
Default Value: ""
A password if authentication is to be used for the proxy.
If AuthScheme is set to Basic Authentication, the User and Password are Base64 encoded and the proxy authentication token will be generated in the form "Basic [encoded-user-password]".
If AuthScheme is set to Digest Authentication, the User and Password fields are used to respond to the Digest Authentication challenge from the server.
If AuthScheme is set to NTLM Authentication, the User and Password fields are used to authenticate through NTLM negotiation.
Port
Integer
Default Value: 80
The TCP port for the proxy Server (default 80). See the description of the Server field for details.
Server
String
Default Value: ""
If a proxy Server is given, then the HTTP request is sent to the proxy instead of the server otherwise specified.
If the Server field is set to a Domain Name, a DNS request is initiated and upon successful termination of the request, the Server field is set to the corresponding address. If the search is not successful, an error is returned.
SSL
ProxySSLTypes
Default Value: 0
Determines when to use SSL for the connection to the proxy. The applicable values are the following:
| psAutomatic (0) | Default setting. The connection to the Server is SSL-enabled for 'https' URL-s, and non SSL-enabled for other URL-s. |
| psAlways (1) | The connection is always SSL-enabled. |
| psNever (2) | The connection is not SSL-enabled. |
| psTunnel (3) | The connection is through a tunneling (HTTP) proxy. |
User
String
Default Value: ""
A user name, if authentication is to be used for the proxy.
If AuthScheme is set to Basic Authentication, the User and Password are Base64 encoded and the proxy authentication token will be generated in the form "Basic [encoded-user-password]".
If AuthScheme is set to Digest Authentication, the User and Password fields are used to respond to the Digest Authentication challenge from the server.
If AuthScheme is set to NTLM Authentication, the User and Password fields are used to authenticate through NTLM negotiation.
Constructors
Constructors are only relevant when configuring adapters in orchestrations.
public Proxy();
public Proxy(string server, int port);
public Proxy(string server, int port, string user, string password);
Config Settings (Gzip Pipeline component)
The adapter accepts one or more of the following configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the adapter, access to these internal properties is provided through the Other property.GZip Config Settings
| 0 (default) | Both Protection and Validation are enabled |
| 1 | Protection is disabled. Validation is enabled. |
| 2 | Validation is disabled. Protection is enabled. |
| 3 | Validation and Protection are disabled. |
Supported Macros
The adapter also supports the following Macros. These values are not case sensitive and would be supplied to a property in the form %MacroName%.