Understanding the Basics

Topics:

When you begin to skin a Fabric agent, you need to make a few decisions regarding the agent package, output directory, agent group, agent name, label, and comments. You must use the available parameters on the Fabric Skinner form to set these values, which are described in this section.

Agent Package

The Agent Package parameter tells the Java compiler where the agent resides.

Similar Java classes are usually placed within the same package. The package com.ibi.agents is reserved for iWay Software agents and should not be used. One suggestion would be to use an abbreviation for your company name. For example, if your company name is My Company, then the package name could be com.mycompany.agents. Note that Java guidelines discourage the use of capital letters in package names.

Output Directory

The Output Directory parameter tells the Skinner where on your system the generated agent and the accompanying translation files will be stored.

You must enter a full directory path that is accessible to this Service Manager instance. Pick a directory outside of the Service Manager's directory structure. Using a directory within the Service Manager's area may cause operational problems or prevent updates from occurring.

Agent Group

The Agent Group parameter allows you to logically group this agent with similar agents. This will help you find your new agent when you create a process flow using iWay Integration Tools (iIT).

By default, the Hyperledger Fabric group is already selected for you, as shown in the following image.

Browse through the available groups by using the scroll bar and select the corresponding group that is most appropriate for your agent. If none of the listed groups are appropriate or you cannot decide, then leave the default Hyperledger Fabric group selected. You can always modify this at a later time.

Agent Name

The Agent Name parameter is the actual Java class name that will be used when the Fabric Wizard generates the Java source code.

When determining an agent name, ensure that the name is descriptive of the class. For example, PostMT101 when the class is used for posting a SWIFT MT101 message (Request for Transfer). Java classes typically have the first character in the name capitalized. In this example, the P in post is capitalized. As a best practice, the first letter of each word that would follow a space in the name of the class is capitalized. In this example, post MT101 becomes PostMT101.

Agent Label

The Agent Label parameter contains a short descriptive sentence.

This sentence should describe precisely what the Fabric agent does. The Agent Label is what is displayed in the selection list when you look for the agent to configure, as shown in the following image.

Agent Comment

The Agent Comment parameter is used to enter more descriptive text about the agent's function.

This comment is used within the Java's JAVADOC and displayed to the user when the agent is selected for configuration, as shown in the following image.

Fabric Channel Provider

The Fabric Channel Provider parameter allows you to select an available Fabric Provider from a drop-down list, as shown in the following image.

Each configured provider will contain the parameters that are required to execute the Fabric transaction (for example, User Name, MSPID, Enrollment Certificate, and so on). Since these parameters are shared between all Fabric chaincode calls and should not change, a provider is used where a centralized repository of Fabric values is available. This topic does not go into detail describing each of those parameters. You can set default values for your Fabric Provider that are appropriate to your application design.

Click the drop-down list to display a list of available Fabric Providers, as shown in the following image.

Select a Fabric Provider from this list. Note that your list will vary. The names and the number of entries are based on the names and number of Fabric Providers that you have configured.

Operation Name

The Operation Name parameter, by convention normally the first argument (Argument 0) to follow Fabric chaincode specific parameters is the Fabric's chaincode operation. In this example, we are going to enter Post, as shown in the following image.

Number of Parms

The Number of Parms parameter allows you to customize the parameters that will be displayed when your Skinned Fabric Agent is presented for configuration.

By default the Fabric Agent displays 5 generic parameters labeled Argument 0 through Argument 4, as shown in the following image.

Each of the above argument (Argument 0 through Argument 4) values would have to be configured at design time. But when you set the Number of Parms to a value other than 0, and define those parameters, the Fabric call parameters become much more relevant and easier for a user to understand and configure, as shown in the following image.

Defining Additional Parameters

Topics:

When you select a number of parameters from the list (up to 10) the skinner displays the parameter configuration block for each parameter, as shown in the following image.

This block shows the default for the first parameter, and is the same for each parameter configuration block that follows.

Parm (Parameter) Name

This is the name that will be used by the Java class to identify the parameter. Based on usage guidelines, the first character in the name is not capitalized. For example, a good parameter name that can be used to identify the source of funds in a financial transaction could be fromAccount. Notice that the first letter in Account was capitalized, which improves readability. Ensure that parameter names are descriptive, but not too long.

Label

The Label parameter is used to identify the parameter to the person who is configuring this agent.

The value (description) entered here should be concise (one to three words). The Description parameter that follows allows you to provide more descriptive content as required.

Description

The Description parameter allows you to enter a detailed description of the field in question.

The description can also include suggestions on possible entries in this field or any other information that would help the user make a valid entry into this field.

Group Name

This parameter is not used at this time and can be left blank.

Required

Clicking on the required field displays a drop-down listing of two choices; required or optional.

This drop-down list allows you to select between the two options.

  • required. Indicates that the person configuring the parameter must make a valid entry in the field. If a field is required a visual queue of "*" follows the field label on the screen.
  • optional. An entry in this field is not necessary and may be left blank by the person configuring the agent.

Type

The type parameter tells the Java class what type of data to expect in this field.

Clicking on this field displays a drop-down list. The Type selected is used by the Service Manager to validate the parameter's data field at design time.

  • integer. The integer type will contain a number that can be written without a fractional component. For example, 21, 4, 0, and ?2048 are integers, while 9.75, 4.8 are not.
  • string. The string type will contain any combination of letters numbers and white space (except tabs).
  • directory. The directory type will contain a fully qualified path to a directory accessible to iSM.
  • file. The file type will contain a fully qualified path to a file accessible to the Service Manager.
  • enumeration. The enumeration type allows you to enter a fixed list of values that the person configuring the agent can choose from during design time. To build the list, enter the value in the field to the left of the Add button. Once a value is specified, click Add to add the entry to the list.

    The entry will then be moved to the list that is forming under the field. To remove an entry from the list. Highlight the entry in the list and click the Delete button.

  • combobox. The combobox type is similar to the enumeration. The combobox allows you to enter a selection of values that the person configuring the agent can choose from but also allow the person to enter a value into the field that is not on the list of values.
  • boolean. The boolean type will display a selection list with only two items in the list true or false.
  • path. Similar to the directory or file types field will contain a fully qualified path to a directory or file that is accessible to iSM.
  • password. Similar to the string type the field will contain any combination of letters numbers and white space (except tabs). The difference is that the value entered will not be shown, in its place each character is replaced by the "*" character.

Default Value

The Default Value is what the Service manager will display to the user at design time.

When you have completed configuring all of the parameters click the Submit button. The generator produces two files:

  • Text properties
  • Agent executable code:
    #Text Strings associated with PostMT101.java
    #Mon Aug 07 11:20:21 EDT 2017
    PostMT101.desc=Posts a SWFT DB/CR from MT101 Message
    PostMT101.amtParm.desc=Amount to transfer in USD
    …

The new agent as generated should be compiled and loaded into an iSM extension. For more information, see the iSM Programmer's Guide. This agent can now be used in a process flow.

The values entered into the fields will be the defaults for the configuration. They can be overridden at the time the agent is configured.