Packaging Connectors

Getting Started

The XMPro Package Manager is a Windows 10 desktop application that enables you to package a new Connector or update details for an existing Connector. See the Connector article for more information on Connectors.

This application takes you through the process of specifying all the properties your Connector requires, adding or changing the controls for each user setting, and uploading the DLL files of the Connector code. It will provide you, upon completion, with a file that can be uploaded to Application Designer after which you can use the Connector in App Pages.

You can download the software from the Microsoft Windows 10 Store or clicking here.

After installing the XMPro Package Manager, launch the application from the Microsoft Store or search for “XMPro Package Manager” in the Start menu and then click on “XMPro Package Manager”.

New / Import

On the first screen of the application, you can either create a new Connector package or import and update an existing one.

Use the arrows at the bottom of the page section to move forward or backward in the application.

Details

The Details form allows you to specify or edit the properties of a Connector. These properties are listed and explained below.

Name

The name of the Connector is what the Connector will be known as once it is uploaded to the Application Designer platform, for example, “SQL Connector”.

Description

The description is a brief explanation of what the Connector does, for example, “This Connector allows you to read/update a SQL Database table“.

Version

The version of the Connector. Any real number is acceptable, for example, "1.02".

If you make a change to an existing Connector, make sure you increment the version number as Application Designer will not allow you to upload two of the same Connectors with the same version.

Entry Point

The entry point is the namespace and class name of the actual Connector’s DLL file.

For example, if a Connector with the class name “Connector” is located in the XMPro.AzureSQLConnectors namespace, the Entry Endpoint for it would be “XMPro.AzureSQLConnectors.Connector”.

Icon File

The icon used to represent your Connector. Click the Browse button, navigate to where you’ve stored the file via the Explorer and select the new image file.

It is recommended that you upload either a JPG or PNG file with a size of 64×64 pixels to accommodate for retina displays.

References

The References form is where you upload the DLL file(s) that were generated when you built the project containing your Connector. You are only required to upload your Connector's DLL file; there is no need to upload the XMPro.Integration.Framework.dll file as this DLL is automatically included.

To upload a file, click on the Browse button next to the DLL File(s) field and navigate to where the files are located and select them. When you’ve selected all the files needed, click on the Add button to add them to the Selected File(s) list. Please note that only files in the Selected File(s) list will be included in the package. To remove a DLL from the list, click on the Delete button next to the DLL name in the Selected File(s) list.

The XMPro Package Manager can package DLL(s) created in .NET.

Settings

Depending on what your Connector does, it might require that the user provide certain information, such as a server URL, username, or password. For each of these information fields (or settings), you need to specify which control should be used and what each control represents, for example, the SQL Connector will require the user to add a server URL. The user should provide this value using a text-box control. Thus, you need to create a control with a type of “TextBox” and a caption that reads “Server URL” in the XMPro Package Manager application.

The following controls are available to be used to capture user input:

Button CheckBox CheckList DropDown EditList FileUpload

Filter Grid Group HTML Editor NumberBox

ScriptBox TextBox Title TokenBox VariableBox

Each control has several properties that have to be set and not all properties apply to all controls. For example, options apply to a drop-down control and not a text-box control.

The table below contains a list of all the available properties, their description, and to which controls they are applicable.

Property Name	Control Type	Description
Allow Custom Text	Drop-Down	Allows the user to type custom text in the drop-down field if checked.
Allow Custom Tokens	Token Box	Allows the user to add custom tokens if checked.
Caption	All	Text that will be displayed with the group or setting. The caption is usually one or two words, describing the value that should be provided by the user, for example, “Server URL”.
Default Value	Title	The default value of the title.
Font Size	Script Box	Size of the font in the Script Box.
Help Text	All, excluding Groups	If you need to provide the user with any additional information about the purpose of the setting or helpful instructions, specify it in this field.
Key	All	Uniquely identifies the group or setting.
Keywords	Script Box	Define your variables or other custom keywords here, so that they will be available in the editor’s IntelliSense.
Options (Drop Down)	Drop-Down	Use the Options-area to add values to the drop-down menu by specifying the Text and Value fields and then clicking Save. You may also choose an option to be used as the default option by checking the “Set as Default Value” box.
Options (HTML Editor)	HTML Editor	Allows you to specify placeholders that can be mapped to input fields in the input received by the Agent.
Postback	All	If checked, will cause the form to do a postback to retrieve values from the server when the field loses focus (when the user clicks out of the field).
Required	All, excluding Groups	The control will be validated to make sure that a value has been specified if this box is checked.
ScriptBox Height	Script Box	Height of Script Box.
ScriptBox Mode	Script Box	Language in which script has to be written.
ScriptBox Theme	Script Box	The theme of the Script Box. Themes available include the following: Ambiance Chaos Chrome Clouds Clouds_midnight Cobalt Cromson_editor Dawn Dreamweaver
ScriptBox Width	Script Box	Width of Script Box.
Secure	All	The value of the control will be treated as a secure value if this box is checked (encrypted and not displayed on the form in plain text). An example of a secure value is a SQL Server password.
Show Grid Lines	Grid	The grid lines of the grid will be shown if checked.
Show Header	Grid	The header of the grid will be displayed, if checked.
Sort Index	All	This is used to determine the group or setting’s position and works with increments of 10. Adjust this value to move the group or setting up or down on the form.
Unique Key	Grid	Mark a specific column as being unique, for example, an identity column.
Visible	All	This field sets the initial visibility of the group or setting.

Adding Settings

Settings are grouped logically into one or more groups, such as authentication, criteria, and output.

Create a group first, then add controls for settings to the group. To do this, follow the steps below:

1. Click on the plus-icon (top right, next to the Settings header). A form section will open, allowing you to specify a group for the settings.

2. Specify a unique value that can be used as the key for the group.

3. Add the caption you would like to use.

4. Click Save.

5. Next, we are going to add a setting. Click on the plus-icon next to the group you’ve created.

6. Choose the type of control you would like to use.

7. Add a unique key for your control. Please note that this key needs to correspond to what you defined in your code.

8. Add a caption for your control.

9. If needed, add a default value.

10. If required, add help text.

11. Select the options that apply from the list of check-boxes.

12. Click Save.

Output

The second last step is to provide the location on the file system where you would like the package to be created. Click on the Browse button and navigate to the folder where you would like the package to be exported, and enter a file name. The file name defaults to the preferred format, category_name_version.xmp.

Tick the checkbox if you would like to export the file as JSON too. It will be saved to the same directory as the XMP file.

If you imported an existing file, ensure you enter a different file name or the original will be overwritten.

Review: Details

Lastly, you can navigate back through the steps to review the details that you’ve specified. If you are satisfied, complete the wizard by clicking the Save button below. Your package will be created as a file with a “.xmp” extension.

If you imported an existing file, take care to either click 'Save As' to generate a new Agent, or click 'Save' to generate a new version of the original Agent. Fu

Further Reading

• How to upload your new Connector to Application Designer

You need to have the correct permissions set against your user to be able to edit and upload Connectors. This is a role not typically given to all users.