Integrate on-premises applications via Nintex Gateway

When an Xtension uses Nintex Gateway, the Nintex Gateway installation on your network receives the operation requests from Nintex Automation Cloud and passes them through to your on-premises application.

The URL for your Nintex Gateway installation is stored in your Nintex Automation Cloud tenant. The {{x-ntx-gateway-uri}} variable tells Nintex Automation Cloud to use that URL as your Xtension's host URL.

In the root level of your OpenAPI Specification, add the x-ntx-host property with a value of {{x-ntx-gateway-uri}}.

Note: Normally, variables used with specification extensions like x-ntx-host need to be listed as additional connection properties. In this case, the {{x-ntx-gateway-uri}} is a special variable Nintex Automation Cloud handles internally. You do not need to define it in your connection properties.

For more information on overriding host paths, see x-ntx-host.

Nintex Gateway can integrate with multiple on-premises platforms such as SharePoint on-premises, Microsoft SQL Server on-premises, and Nintex RPA. To make sure requests from this Xtension are handled correctly by Nintex Gateway, replace the basePath with the/xtension/ value to flag these operations as an Xtension.

Note: The on-premises service URL, where your on-premises application expects to receive requests, is collected by your Xtension's connection properties when your workflow designers create a connection. See Add a connection property for the on-premises service URL, below.

In the root level of your OpenAPI Specification, change the value of the basePath property to /xtension/.

Nintex Gateway validates all new connections The stored authorization credentials for a connector. using a special validation endpoint The address of a specific resource provided by the third-party API.. If this operation is used then Nintex Gateway will check that it can reach (on a network level) the baseurl of the on-premises application. This validates the connection from Nintex Automation Cloud to Nintex Gateway and the network connection from Nintex Gateway to the baseurl.

The /x-ntx-validate endpoint allows you to define this validation operation without hard-coding your Nintex Gateway URLs in your OpenAPI Specification. This endpoint is converted to the full validation URL when validating the connection.

In the paths object:

1. Add a new operation A single request to a third-party API. Operations often become actions in the workflow designer. of /x-ntx-validate.
2. Add a GET HTTP method The HTTP action to perform on the endpoint, such as GET, POST, DELETE, PUT. In defined inside the operation's path object in the OpenAPI specification..
3. Add an operationId of validateConnection.
4. Add the property x-ntx-visibility with a value of internal.
5. Add a response The return from a third-party API after a request has been made by the client. object of 200.
6. Add a response object of default for all other response codes.

You can also define your own validation endpoint if you prefer.

The x-ntx-visibility property hides this operation within Nintex Automation Cloud so it doesn't clutter your Action toolbox.

For more information on defining operations, see our basic OpenAPI Specification tutorial: Define the operations.

To ensure Nintex Automation Cloud validates your Nintex Gateway URL when creating a connection, add the validation URL to the security definition using the x-ntx-connection-validation specification extension.

In the securityDefinition object:

1. Create an object for basic authentication Identifying the API requestor using a username and password passed in the HTTP header., if one doesn't already exist.

See Add basic authentication for help with creating basic authentication security definitions.

2. Inside the basic security definition, add the x-ntx-connection-validation property.
3. Inside the x-ntx-connection-validation property, add the property operationId with a value of validateConnection.

This tells Nintex Automation Cloud to use the validation operation we defined earlier. You can also define your own validation operations the same way.

For more information on validation operations, see x-ntx-connection-validation.

To add connection properties to the security definition:

1. Inside the basic security definition, add the x-ntx-connection-properties object.
2. Inside the x-ntx-connection-properties object:
   1. Add a type property with a value of object.
   2. Add a properties object.

We will add the connection properties to this properties object in the next steps.

For more information on defining custom connection properties, see x-ntx-connection-properties.

Your Nintex Automation Cloud tenant may have more than one Nintex Gateway integration. Add the x-ntx-gateway-id connection property so your workflow designers can select from a drop-down list of existing Nintex Gateway integrations when they create their connections.

Inside the properties object of x-ntx-connection-properties:

1. Add an x-ntx-gateway-id object.
2. Inside the x-ntx-gateway-id object:
   1. Add a type property with the value of string.
   2. Add a title property with the value Select Nintex Gateway.

The service URL is the base URL where your on-premises application expects to receive requests from integrating services. It is combined with the operation paths defined in the path object to create the complete endpoints.

Add the x-ntx-gateway-xtension-baseurl property to store the service URL:

Inside the properties object of x-ntx-connection-properties:

1. Add an x-ntx-gateway-xtension-baseurl object.
2. Inside the x-ntx-gateway-xtension-baseurl object:
   1. Add a type property with the value of string.
   2. Add a title property with the value On-premises service URL.
   3. Add a description property with the value Base URL of the on-premises service, including HTTPS://.
   4. Add a pattern property with the value of ^(https?:\/\/[^\/?#]+)(?:[\/]|\/.+|)$.

The pattern property ensures your workflow designers see an error if they type a malformed URL, such as forgetting the HTTPS://. It does not check if the URL is the correct URL for your application. For more information on using the pattern property, see Validate with regex.

Note: This topic shows using basic authentication against the on-premises application.

Add username and password connection properties to collect the username and password that will be supplied to the on-premises application when making requests.

Inside the properties object of x-ntx-connection-properties:

1. Add a username object.
2. Inside the username object:
   1. Add a type property with the value of string.
   2. Add a title property with the value On-premises username.

   The title is the label shown for this field when creating the connection. You can change the value to something more specific if needed.

3. Add a password object.
4. Inside the password object:
   1. Add a type property with the value of string.
   2. Add a title property with the value On-premises password.
   3. Add a format property with the value password.

If your network supports authentication via Active Directory, your workflow designers can provide their Active Directory username and password when creating connections for this Xtension.

Inside the properties object of x-ntx-connection-properties:

1. Add an x-ntx-gateway-username object.
2. Inside the x-ntx-gateway-username object:
   1. Add a type property with the value of string.
   2. Add a title property with the value Active Directory username.

   The title is the label shown for this field when creating the connection. You can change the value to something that suits your organization's terms.

3. Add an x-ntx-gateway-password object.
4. Inside the x-ntx-gateway-password object:
   1. Add a type property with the value of string.
   2. Add a title property with the value Active Directory password.
   3. Add a format property with the value password.

If your network does not use Active Directory, you can generate an API key within Nintex Gateway to secure your requests.

Inside the properties object of x-ntx-connection-properties:

1. Add an x-ntx-gateway-apikey object.
2. Inside the x-ntx-gateway-apikey object:
   1. Add a type property with the value of string.
   2. Add a title property with the value Nintex Gateway API key.

For more information on using Nintex Gateway API keys, see Nintex Gateway API keys.

Connection properties added with x-ntx-connection-properties are optional by default, meaning the workflow designer can leave them blank and still successfully create the connection.

For Nintex Gateway, all the connection properties we've defined are necessary, so we need to designate them as required. The workflow designer will not be able to create a connection unless they complete all the additional information.

Inside the properties object of x-ntx-connection-properties:

1. Add a required property.
2. For the value of the required property, add an array of the property names of each connection property you created.

The example shows the required array for an Xtension using Active Directory authentication.

Add complex object support to your OpenAPI Specification using x-ntx-render-version: 2.

In the root level of your OpenAPI Specification, add the x-ntx-render-version property with a value of 2.

For more information on complex object support, see Send arrays or complex objects