Example custom protocols

The examples below provide a business process, AFTExtensionsCustomer.xml file, and AFTExtensionsCustomer.properties file for adding Sterling Connect:Enterprise® for UNIX or HTTP Send. You can use these as a model for creating the files to add other custom protocols.

The AFTRouteViaCEU and AFTRouteViaHTTP business processes referred to in this section are available in your Sterling Integrator installation at <install>/samples/aft/extensions_sample/ (with the extension .bpml.). Sample AFTExtensionsCustomer.xml and AFTExtensionsCustomer.properties files are included in the same directory. For more information, see <install>/samples/aft/extensions _sample/README.txt.

ProcessData for business processes implementing custom protocols

The following elements are available in ProcessData when the business process implementing an custom protocol is executed:

Element	Description
Primary document	The primary document contains the data as it will be delivered to the consumer, so that, if the producer's document required PGP operations (such as decryption) or the consumer required PGP processing, the contents of the primary document contains the results of performing those PGP operations.
PrimaryDocumentId	Document ID for the primary document
DestinationMessageName	Name of the primary document
TransportBP	Name of the business process that will be executed for the protocol
AFTRouteId	An internal identifier needed if the AFT Route Progress Event Reporting service is called. The value of this element must not be changed by the extensibility business process.
AFTRouteWorkFlowId	An internal work flow identifier needed if the AFT Route Progress Event Reporting service is called. The value of this element must not be changed by the extensibility business process.
ProducerName	Name of the data producer
ConsumerName	Name of the data consumer
Parameters added to AFTExtensionsCustomer.xml	Any parameters you supply as part of your custom protocol are available in process data.

Example adding an Sterling Connect:Enterprise for UNIX extension

For example, if you were adding Sterling Connect:Enterprise for UNIX as a outbound file transfer mechanism, your business process could be the following:

<process name="AFTRouteViaCEU">
<sequence>
	<operation name="CEU Add Service">
		<participant name="CEUServerAdd"/>
		<output message="AddRequest">
			<assign to="." from="*"/>
			<assign to="CEUServerAdapterInstanceName"
				from="string(CEUServerAdapterInstanceName)"/>
			<assign to="CEUMailboxId" from="string(CEUMailboxId)"/>
		</output>
		<input message="inmsg">
			<assign to="CEUAddServiceResults" from="*"/>
		</input>
		</operation>
</sequence>
</process>

Note: ProcessData does not include the producer name or consumer name for custom protocol business processes.

AFTExtensionsCustomer.xml adding Sterling Connect:Enterprise for UNIX

The following is an example AFTExtensionsCustomer.xml adding Sterling Connect:Enterprise for UNIX for outbound file transfer:

<AFTExtensions>
	<AFTExtension name="ceu-protocol" type="consumer-delivery-protocol"
	label="cdp.protocol.label.ceuprotocol" bp="AFTRouteViaCEU">
		<GROUP title="ceu.instance.group1.title">
		<VARDEF varname="CEUServerAdapterInstanceName" type="String" htmlType="text"
			validator="ALPHANUMERIC" size="30" maxsize="250"
			label="cdp.label.ceuprotocol.ceuserveradapterinstancename" defaultVal="BP"
       required="yes"/>
		<VARDEF varname="CEUMailboxId" type="String" htmlType="text"
			validator="ALPHANUMERIC" size="30" maxsize="250"
			label="cdp.label.ceuprotocol.ceumailboxid" required="no"/>
		</GROUP>
	</AFTExtension>
</AFTExtensions>

AFTExtensionsCustomer.properties adding Sterling Connect:Enterprise for UNIX

The following is an example AFTExtensionsCustomer.properties adding Sterling Connect:Enterprise for UNIX for outbound file transfer:

#######################################################
# Connect:Enterprise UNIX
#######################################################
cdp.protocol.label.ceuprotocol = Connect:Enterprise UNIX
ceu.instance.group1.title = Connect:Enterprise UNIX
cdp.label.ceuprotocol.ceuserveradapterinstancename = 
CEU Server Adapter Instance Name
cdp.label.ceuprotocol.ceumailboxid = Connect:Enterprise UNIX Mailbox Id

Example adding an HTTP Send extension

The following is a business process that adds the HTTP protocol:

<process name="AFTRouteViaHTTP">
	<sequence>
		<operation name="HTTP Client Begin Session Service">
			<participant name="HTTPClientBeginSession"/>
			<output message="HTTPClientBeginSessionServiceTypeInputMessage">
				<assign to="." from="*"/>
				<assign to="HTTPClientAdapter">HTTPClientAdapter</assign>
				<assign to="RemoteHost" from="string(RemoteHost)"/>
				<assign to="RemotePasswd" from="revealObscured(RemotePasswd)"/>
				<assign to="RemotePort" from="string(RemotePort)"/>
				<assign to="RemoteUserId" from="string(RemoteUserId)"/>
				<assign to="UsingRevealedPasswd">true</assign>
			</output>
			<input message="inmsg">
				<assign to="." from="*"/>
			</input>
		</operation>
		<operation name="HTTP Client POST Service">
			<participant name="HTTPClientPost"/>
			<output message="HTTPClientPostServiceTypeInputMessage">
				<assign to="." from="*"/>
				<assign to="DocumentId" from="string(DocumentId)"/>
				<assign to="RawRequest">false</assign>
				<assign to="RawResponse">true</assign>
				<assign to="ResponseTimeout">60</assign>
				<assign to="SessionToken" from="string(SessionToken)"/>
				<assign to="ShowResponseCode">true</assign>
				<assign to="URI" from="string(URI)"/>
			</output>
			<input message="inmsg">
				<assign to="." from="*"/>
			</input>
		</operation>
		<operation name="HTTP Client End Session Service">
			<participant name="HTTPClientEndSession"/>
			<output message="HTTPClientEndSessionServiceTypeInputMessage">
				<assign to="." from="*"/>
			</output>
			<input message="inmsg">
				<assign to="." from="*"/>
			</input>
		</operation>
	</sequence>
</process>

Notice the process above uses the revealObscured(RemotePasswd) Xpath function. This is needed because every parameter defined in AFTExtensionsCustomer.xml of htmlType=”Password” is stored either encrypted (if the parameter name has a suffix of "_ENCRYPTED") or obscured (for all other parameters of htmlType=”Password”). In this specific case, the password is passed into the BP as an obscured value but the HTTP Client Adapter requires a password that is not obscured (because UsingRevealedPasswd is set to "true").

When extending protocols and using passwords consider how the service or adapter you plan to use accepts passwords.

AFTExtensionsCustomer.xml for HTTP Send

The following is an example AFTExtensionsCustomer.xml file to add HTTP Send support to Sterling File Gateway :

<AFTExtension name="http-protocol" type="consumer-delivery-protocol"
		label="cdp.protocol.label.httpprotocol" bp="AFTRouteViaHTTP">
		<GROUP title="http.instance.group1.title">
		<VARDEF varname="RemoteHost" type="String" htmlType="text" 
			validator="ALPHANUMERIC" size="20" maxsize="20"
			label="cdp.label.httpprotocol.httpip" required="yes"/>
		<VARDEF varname="RemotePort" type="String" htmlType="text" 	
			validator="ALPHANUMERIC" size="20" maxsize="20"
			label="cdp.label.httpprotocol.httpport" required="no"/>
		<VARDEF varname="RemoteUserId" type="String" htmlType="text"
			validator="ALPHANUMERIC" size="20" maxsize="20"
			label="cdp.label.httpprotocol.httpuser" required="no"/>
		<VARDEF varname="RemotePasswd" type="String" htmlType="password"
			validator="ALPHANUMERIC" size="20" maxsize="20"
			label="cdp.label.httpprotocol.httppassword" required="no"/>
		<VARDEF varname="URI" type="String" htmlType="text" validator="ALPHANUMERIC"
			size="20" maxsize="20" label="cdp.label.httpprotocol.uri" required="no"/>
	</GROUP>
</AFTExtension>

The mandatory parameter for this example is Remote Host. Optional parameters include Remote Port, Remote User Id, Remote Password, and URI.

AFTExtensionsCustomer.properties for HTTP Send

The following is an AFTExtensionsCustomer.properties file to add HTTP Send support to Sterling File Gateway :

#######################################################
HTTP Send
####################################################### 
cdp.protocol.label.httpprotocol = HTTP Send
http.instance.group1.title = HTTP Send
cdp.label.httpprotocol.httpip = HTTP IP Address
cdp.label.httpprotocol.httpport = HTTP Port
cdp.label.httpprotocol.httpuser = HTTP User
cdp.label.httpprotocol.httppassword = HTTP Password
cdp.label.httpprotocol.uri = URI

The user interface created by this example AFTExtensionsCustomer.properties file adds the attribute for cdp.protocol.label.httpprotocol in the Protocol list.

In the next page of the Create Partner wizard, the following elements and attributes are added:

cdp.protocol.label.httpprotocol is at the top of the white screen
http.instance.group1.title is title in parameter box
cdp.label.httpprotocol.httpip parameter label
cdp.label.httpprotocol.httpport parameter label
cdp.label.httpprotocol.uri parameter label

In the next page of the Create Partner wizard, the following elements and attributes are added:

cdp.protocol.label.httpprotocol is at the top of the white screen
http.instance.group2.title is the title in parameter box
cdp.label.httpprotocol.httpuser parameter label
cdp.label.httpprotocol.httppassword parameter label

Encrypted passwords

If you include an "_ENCRYPTED" suffix on a parameter it causes the user-entered values to be encrypted when saved (use only for fields of htmlType=”Password”). Do not use the revealObscured() function with passwords that are encrypted. Rather, use the encrypted password only if the particular service to be invoked can accept an encrypted password and decrypt it internally.

If a value is declared to be of type "password" and does not have an "_ENCRYPTED" suffix, the value is saved into the database obscured and delivered to ProcessData obscured. Call the revealPassword (Xpath) XPath function to reveal the password, immediately before using the password.

Example adding an FTPS extension

For example, if you were adding FTPS as a outbound file transfer mechanism, AFTExtensionsCustomer.xml could be the following:

<!--Custom FTP/S Protocol for internal and external connections  -->
  <AFTExtension name="custom-ftps-protocol" type="consumer-delivery-protocol"
     label=	"custom.ftps.protocol.label" 
     bp="CustomFileGatewayDeliverFTPS">
    <GROUP title="custom.ftps.instance.group1.title">
      <VARDEF varname="FTPLocation" type="String" htmlType="select" 
         validator="ALPHANUMERIC" size="30" maxsize="250" 
         label="custom.ftps.protocol.label.ftplocation" 
         options="CUSTOMInternalExternal" required="yes" defaultVal="External"/>
      <VARDEF varname="HostName" type="String" htmlType="text"
         validator="ALPHANUMERIC" 
         size="30" maxsize="250" label="custom.ftps.protocol.label.hostname"
         required="yes"/>
      <VARDEF varname="Port" type="String" htmlType="text"
        validator="ALPHANUMERIC"
        size="30" maxsize="250" label="custom.ftps.protocol.label.port"
        required="yes"/>
      <VARDEF varname="ConnectionType" type="String" htmlType="select"
        validator="ALPHANUMERIC" size="30" maxsize="250"
        label="custom.ftps.protocol.label.connectiontype" 
        options="CUSTOMFTPConnType" required="yes"/>
      <VARDEF varname="Username" type="String" htmlType="text"
        validator="ALPHANUMERIC" size="30" maxsize="250"
        label="custom.ftps.protocol.label.user" required="yes"/>
      <VARDEF varname="ObscuredRemotePasswd" type="String" htmlType="password"
        validator="ALPHANUMERIC" 
        size="30" maxsize="250" label="custom.ftps.protocol.label.remotepasswd"
        required="yes"/>
      <VARDEF varname="CACertificateId" type="String" htmlType="select"
         validator="ALPHANUMERIC" 
         size="30" maxsize="250"
         label="custom.ftps.protocol.label.cacertificateid"
         options="CACertListerbyID" required="no"/>
      <VARDEF varname="SystemCertificateId" type="String"
         htmlType="select" validator="ALPHANUMERIC" 
         size="30" maxsize="250"
         label="custom.ftps.protocol.label.systemcertificateid"
         options="SystemCertListerbyID" required="no"/>
      <VARDEF varname="SSL" type="String" htmlType="select"
        validator="ALPHANUMERIC"
        size="30" maxsize="250" label="custom.ftps.protocol.label.ssl"
        options="CUSTOMSSLMode" required="yes" defaultVal="SSL_EXPLICIT"/>
      <VARDEF varname="CipherStrength" type="String" htmlType="select"
        validator="ALPHANUMERIC" 
        size="30" maxsize="250"
        label="custom.ftps.protocol.label.cipherstrength"
        options="CUSTOMCipherStrength" required="yes" defaultVal="STRONG"/>
      <VARDEF varname="ClearControlChannel" type="String" htmlType="select"
         validator="ALPHANUMERIC" 
        size="30" maxsize="250"
        label="custom.ftps.protocol.label.clearcontrolchannel"
        options="CUSTOMClearControlChannel" required="yes" defaultVal="NO"/>
      <VARDEF varname="BaseDirectory" type="String" htmlType="text"
        validator="ALPHANUMERIC" size="30" maxsize="250" 
        label="custom.ftps.protocol.label.directory" required="no"/>
      <VARDEF varname="Retries" type="String" htmlType="text"
        validator="ALPHANUMERIC" size="30" maxsize="250"
        label="custom.ftps.protocol.label.retries" required=
		   "Yes" defaultVal="3"/>
      <VARDEF varname="RetryInterval" type="String" htmlType="text"
        validator="ALPHANUMERIC" size="30" maxsize="250"
        label="custom.ftps.protocol.label.retryinterval" required="Yes"
        defaultVal="1"/>
    </GROUP>
  </AFTExtension>
  <OPTION name="CACertListerbyID"
          class="com.sterlingcommerce.woodstock.ui.CACertLister"/>
  <OPTION name="SystemCertListerbyID
   " class="com.sterlingcommerce.woodstock.ui.SystemCertLister"/>
  <OPTION name="CUSTOMInternalExternal">
    <ELE value="Internal" displayname="custom.internal"/>
    <ELE value="External" displayname="custom.external"/>
  </OPTION>
  <OPTION name="CUSTOMFTPConnType">
    <ELE value="ACTIVE" displayname="custom.active"/>
    <ELE value="PASSIVE" displayname="custom.passive"/>
  </OPTION>
  <OPTION name="CUSTOMSSLMode">
    <ELE value="SSL_EXPLICIT" displayname="custom.ssl_explicit"/>
    <ELE value="SSL_IMPLICIT" displayname="custom.ssl_implicit"/>
  </OPTION>
  <OPTION name="CUSTOMCipherStrength">
    <ELE value="ALL" displayname="custom.ciperhAll"/>
    <ELE value="STRONG" displayname="custom.ciperhStrong"/>
    <ELE value="WEAK" displayname="custom.ciperhWeak"/>
  </OPTION>
  <OPTION name="CUSTOMClearControlChannel">
    <ELE value="YES" displayname="custom.yes"/>
    <ELE value="NO" displayname="custom.no"/>
  </OPTION>

The following is an AFTExtensionsCustomer.properties file to add FTPS support to Sterling File Gateway:

#######################################################
# CUSTOM custom FTPS listening consumer
#######################################################
custom.ftps.protocol.label=CUSTOM FTP/SSL
custom.ftps.instance.group1.title=FTP/SSL Parameters
custom.ftps.protocol.label.ftplocation=Internal or External FTP Server:
custom.ftps.protocol.label.hostname=FTP Server Host Name(or IP address):
custom.ftps.protocol.label.port=FTP Listen Port:
custom.ftps.protocol.label.connectiontype=Connection Type:
custom.ftps.protocol.label.user=User Name:
custom.ftps.protocol.label.remotepasswd=Password:
custom.ftps.protocol.label.directory=Base Directory:
custom.ftps.protocol.label.retries=Number of retries:
custom.ftps.protocol.label.retryinterval=Interval between retries (in minutes):
custom.ftps.protocol.label.cacertificateid=Partner's Self-Signed Certificate Id:
custom.ftps.protocol.label.systemcertificateid=System Certificate Id Used 
To Identify Client to Server
custom.ftps.protocol.label.ssl=SSL Negotiation, Explicit or Implicit
custom.ftps.protocol.label.cipherstrength=SSL Cipher Strength
custom.ftps.protocol.label.clearcontrolchannel=Enable Clear Control Channel
#######################################################
# CUSTOM Custom labels for OPTION Elements
#######################################################
custom.internal=Internal
custom.external=External
custom.active=Active
custom.ssl_explicit=Explicitustom.passive=Passive
custom.ssl_explicit=Explicit
custom.ssl_implicit=Implicit
custom.ciperhAll=ALL
custom.ciperhStrong=STRONG
custom.ciperhWeak=WEAK
custom.yes=YES
custom.no=NO