Use External Start

Enterprise Edition for Nintex Workflow 2016 is required for this feature. If using perpetual licensing, then valid software assurance is also required.

Nintex external platform is required for this feature. For details, see Enable Nintex external platform features.

External Start allows you to initiate site workflows from outside of SharePoint. You can configure workflows for External Start; generate (add) External Start endpoint URLs; delete, disable, and enable External Start URLs; connect external services; and view External Start usage.

For more information, click a link below.

How External Start works​​​

Configure workflows for External Start​

Add and delete External Start URLs​​

Connect external services​​​​

Disable and enable External Start URLs​​

View External Start usage

Troubleshooting

For administrative settings, see Manage External Start settings.

How External Start works​​​

External Start lets you initiate site workflows from outside of SharePoint by providing you the ability to generate endpoint URLs pointing to the workflows. Each endpoint URL stores the workflow infomation along with its start variables of supported data types (if any). Endpoint URLs reference run.nintex.io. 

Example endpoint URL: https://run.nintex.io/x-start/weuyj1TkGD​​

For example, you could use an external service (integration partner) such as Zapier or Azuqua to monitor Salesforce for new customers and initiate a Nintex workflow to create customer-specific SharePoint sites. You could configure this service to map Salesforce data from another service to Nintex workflow variables for use in the workflow. You could also create your own code to reference the endpoint URLs. When the endpoint URL is called, the associated workflow is initiated.

To use External Start, an administrator must enable External Start using Central Administration. For variable mapping, a workflow designer configures start variables of supported data types. The workflow designer publishes the site workflow and generates one or more External Start endpoint URLs for this workflow. Nintex stores the generated endpoint URLs and their associated security keys. The workflow designer configures an external service or manual code to reference the External Start endpoint URL and associated security key. When the service or code calls the endpoint URL, the associated workflow is initiated when required conditions exist (such as new Salesforce customers). Once the service or code is set up and monitoring, nothing more needs to be done.​

Configure workflows for External Start​

Published site workflows have External Start functionality available. If you want to make variables available for mapping to another service, such as Salesforce, then configure variables to show on start; select Yes for Show on start form. Variables can be mapped using configuration screens in external services such as Zapier or Azuqua.

Data types supported for variables used with External Start:

  • Single line of text

  • Multiple lines of text

  • Choice

  • Number

  • Date and Time

  • Yes/No

No workflow settings are required for External Start. It is acceptable to select the option Start manually.

Add and delete External Start URLs​​

You can add and delete multiple External Start endpoint URLs per workflow. Delete endpoint URLs when the associated workflow or external service will no longer be used. For example, if you change accounting providers, then any endpoint URLs created specifically for the old provider can be deleted. If you only want to temporarily ignore calls to the endpoint URL, you can disable the URL. See instructions later in this topic.

Note: Only published site workflows can use External Start.

To access the External Start URL page

  1. Do one of the following.

    • Click the settings icon () on the upper right and then select Nintex Workflow to display the Nintex Workflow for SharePoint 2016 page.

    • Click the settings icon () on the upper right and then select Site settings to display the Site Settings page.

  2. Under Nintex Workflow, select External Start URL.

To access the External Start URL configuration page for a given workflow​

  1. Access the External Start URL page by doing one of the following.
    • ​​Click (Settings) on the upper right of the page, select Nintex Workflow, and then select External Start URL under Nintex Workflow.
    • On the Site Settings page, in the Nintex Workflow section, click External Start URL.

    The External Start URL page is displayed, listing all External Start URLs for all workflows.

  2. Click Configure for the workflow of interest.

    The External Start URL configuration page for the selected workflow is displayed. The selected workflow is indicated in the page title.

To add an External Start endpoint URL

  1. Access the External Start URL page.

    For instructions, see the above procedure.

  2. On the External Start URL page, click Configure for the workflow of interest. 

    The External Start URL configuration page for the selected workflow is displayed. The selected workflow is indicated in the page title.

  3. On the External Start URL configuration page, click Add URL. 

    After a moment, the new endpoint URL is displayed on the page. By default, the new endpoint URL is enabled. ​The endpoint URL references run.nintex.io.

    Example endpoint URL: https://run.nintex.io/x-start/weuyj1TkGD​​

    A security key is generated at the same time as the endpoint URL; both items are stored securely by Nintex.

  4. (Optional.) Enter a name for the endpoint URL using the text box under the column Internal URL name for reference. 

    The endpoint URL is now available for connecting to external services. 

    Note: Keep External Start URLs secure. Variable names and data types can be identified from the URLs when used outside the Nintex platform.

To delete an External Start endpoint URL

  1. Access the External Start URL page.

    For instructions, see the above procedure.

  2. On the External Start URL page, click Configure for the workflow of interest. 

    The External Start URL configuration page for the selected workflow is displayed. The selected workflow is indicated in the page title.

  3. On the External Start URL configuration page, under the Delete column for the endpoint URL of interest, click X (Delete) and then click OK to confirm. 

    After a moment, the page refreshes and the deleted endpoint URL is no longer displayed.

​​Track variables​​

The best practice for tracking variables in the initiated workflow is to use the Log in the History List workflow action to log the variable values to history. For more information about this action, see Log in the History List.

Connect external services​​​​

You can connect external services to an endpoint URL by copying and pasting the URL and its associated security key to the external service configuration.

To copy an endpoint URL to an external service

  1. Access the External Start URL page.

    For instructions, see the above procedure.

  2. On the External Start URL page, click Configure for the workflow of interest. 

    The External Start URL configuration page for the selected workflow is displayed. The selected workflow is indicated in the page title.

  3. On the External Start URL configuration page, under the URL and security key column for the endpoint URL of interest, click View Details. 

    Note: Keep External Start URLs secure. Variable names and data types can be identified from the URLs when used outside the Nintex platform.

  4. In the View details dialog box, click Copy URL to copy the endpoint URL. 

    Example endpoint URL: https://run.nintex.io/x-start/weuyj1TkGD​​

  5. In the external service configuration, paste the copied endpoint URL.

  6. In the View details dialog box, click Copy security key to copy the security key. For more information, see Authentication and authorization.

    The External Start feature included with Nintex Workflow 2016, requires that, for certain REST operations, you provide a hash-based message authentication code (HMAC) digest value with which to submit a request to start a workflow using that endpoint URL. For example, an HMAC digest value is required to submit a request to start a workflow, but not required to retrieve information about workflow variables.

    The HMAC digest value is calculated using the following values:

    • Security key - The security key is associated with the External Start endpoint URL, and generated by Nintex Workflow Management. Ensure that you have both the External Start endpoint URL and corresponding security key before sending a request to the External Start service to start a workflow. Ensure that you have the most current security key prior to calculating the HMAC for a request.

    • HTTP method name - The HTTP method name of the request, in lower case. For example, to request that the External Start service start a workflow, this value would be set to "post".

    • Endpoint URL - The relative path of the endpoint URL, in lower case.

    • Nonce - A generated random token, used only once, for the request. Typically, a new GUID is used as the nonce for a request to the External Start service. The nonce is included in the request as the value of the X-Api-Nonce request header.

    • Timestamp - A Coordinated Universal Time (UTC) timestamp, in ISO 8601 format, for the request. The timestamp is included in the request as the value of the X-Api-Timestamp request header.

    • Request body - The body of the request, if included in the request.

    The HMAC digest value must be calculated using the SHA-256 algorithm, by performing the following steps:

    1. Concatenate a delimited string, using a colon (:) character as the delimiter, from the HTTP method name, endpoint URL, nonce, timestamp, and request body.

    2. Encode the string in UTF-8 format.

    3. Encode the security key in UTF-8 format.

    4. Calculate a keyed hash with the SHA-256 algorithm, using the security key as the key and the delimited string as the data.

    The resulting keyed hash value is then included in the request as the value of the X-Api-Digest header. The combination of HMAC digest value, nonce, and timestamp values must be provided in the corresponding request headers, and they can only be used for that request. For each request, a new nonce, timestamp, and HMAC digest value must be provided.

    The following C# example, included with the ExternalStart sample, demonstrates how to calculate the HMAC.


    	
public string CalculateDigest (string securityKey, string httpMethod, string path, string nonce, 
    string timestamp, string requestBody)
  { 
	// The data values are concatenated into a single string, 
	// in which each data value is delimited by a colon (:) character, 
	// which is then encoded as a UTF-8 byte array.
	var dataBytes = Encoding.UTF8.GetBytes(String.Join(":", httpMethod, path, nonce, timestamp, 
	requestBody));
	
	// The security key is encoded as a UTF-8 byte array.
	var keyBytes = Encoding.UTF8.GetBytes(securityKey);
	
	// Using the HMACSHA256 object provided by .NET Framework, 
	// the data values are hashed, using the security key. 
	// The value is converted into a string, and any 
	// dashes included after conversion are removed.
	using (var hasher = new HMACSHA256(keyBytes))
	{
	  var hashBytes = hasher.ComputeHash(dataBytes);
	  return BitConverter.ToString(hashBytes).Replace("-", "");
	}
  }

  7. In the external service configuration, paste the copied security key.

    Note: For instructions on selecting services for monitoring (such as Salesforce), mapping variables, and other configuration details, see the documentation for the external service. For example, see Zapier help at https://zapier.com/help/ or Azuqua help at http://help.azuqua.com/help.

Disable and enable External Start URLs​​

Disable External Start endpoint URLs when you want to temporarily avoid use. When an endpoint URL is disabled, the associated workflow does not get initiated by any calls to that endpoint URL. If you want to stop all use of an endpoint URL, you can delete the URL. See instructions earlier in this topic.

To disable or enable an endpoint URL

  1. Access the External Start URL page.

    For instructions, see the above procedure.

  2. On the External Start URL page, click Configure  for the workflow of interest. 

    The External Start URL configuration page for the selected workflow is displayed. The selected workflow is indicated in the page title.

  3. On the External Start URL configuration page, under the Status column for the endpoint URL of interest, select the desired status.

  4. Click Save.

View External Start usage

View External Start usage to determine which published site workflows on the current site have endpoint URLs and understand usage of those endpoint URLs.

To view External Start usage for a site (access the External Start URL page)

  1. Do one of the following.

    • Click the settings icon () on the upper right and then select Nintex Workflow to display the Nintex Workflow for SharePoint 2016 page.

    • Click the settings icon () on the upper right and then select Site settings to display the Site Settings page.

  2. Under Nintex Workflow, select External Start URL.

Troubleshooting

This section provides information for troubleshooting unavailability of External Start.

External Start opti​ons not available

  • Do you have the required license?

    Your license must be enabled for Enterprise Edition and the Nintex external platform (previously called "Nintex Live").

  • Are both the Nintex external platform and External Start enabled?

    To enable the Nintex external platform and External Start, see Manage External Start settings.

  • Was the workflow last published before External Start was enabled?

    External Start options continue to be unavailable for existing published site workflows. To make External Start options available for these workflows, republish them after enabling External Start.

  • Did you update the workflow recently without publishing?

    If you recently updated variables for the workflow, make sure you republish. External Start is available for published site workflows only.

​​​​

Workflow doesn’t start

If the workflow didn’t start after you ran a service pointed to the External Start URL, review the possible causes below.

Cause

Resolution

Workflow error. The External Start URL was successfully called and the workflow started, but the workflow ran into issues before expected actions completed.

See External Start URLs page. An incremented value in the Calls column indicates that an External Start URL for this workflow was called. You can also check workflow history for workflow errors.

Service monitoring frequency. The External Start URL is not yet called because the service is subject to a monitoring frequency.

See the service documentation on monitoring frequency. For example, some Zapier plans monitor every 15 minutes.

Service connection issue. The External Start URL was not called because the service could not connect.

See the service logs and documentation.

Service configuration variable mismatch. The variables specified in the service configuration do not match the variables configured in the workflow. This issue can occur when you update the workflow after configuring the service.

Compare the service configuration to the workflow configuration to ensure that variables match.

Required service not running. The Windows service Nintex Workflow Start Service is not running on the Central Administration server.

On the Central Administration Home page, click System Settings, and then click Manage services on server. Ensure that the status for the service Nintex Workflow Start Service is Started.

Related information

External Start URL page

External Start URL configuration page

​