Back Forward Home Print
Nintex Workflow 2013 > Using the Workflow Designer
Using External Start
​​​​* This topic applies to Nintex Workflow Enterprise Edition only

This topic describes External Start for Nintex Workflow 2013 and provides instructions for use with workflows. 

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. This topic also provides troubleshooting tips. 

For administrative settings, see Managing External Start settings.

How External Start works

External Start allows you to 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. 
 

Configuring 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. 

Adding and deleting 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 add an External Start endpoint URL
  1. Access the Manage External Start page using one of the following methods. 
    • ​​Click the Settings icon on the upper right of the page, select Nintex Workflow 2013, and then select Manage External Start. 
    • On the Site Settings page, in the Nintex Workflow section, click Manage External Start.
  2. On the Manage External Start page, click Configure for the workflow of interest. 
    The Manage External Start configuration page for the selected workflow is displayed. The selected workflow is indicated in the page title. 
  3. On the Manage External Start 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 Manage External Start page using one of the following methods. 
    • ​​Click the Settings icon on the upper right of the page, select Nintex Workflow 2013, and then select Manage External Start. 
    • On the Site Settings page, in the Nintex Workflow section, click Manage External Start.
  2. On the Manage External Start page, click Configure for the workflow of interest. 
    The Manage External Start configuration page for the selected workflow is displayed. The selected workflow is indicated in the page title. 
  3. On the Manage External Start 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    . 

​​Tracking 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.

Connecting 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 Manage External Start page using one of the following methods. 
    • ​​Click the Settings icon on the upper right of the page, select Nintex Workflow 2013, and then select Manage External Start. 
    • On the Site Settings page, in the Nintex Workflow section, click Manage External Start.
  2. On the Manage External Start page, click Configure for the workflow of interest. 
    The Manage External Start configuration page for the selected workflow is displayed. The selected workflow is indicated in the page title.
  3. On the Manage External Start 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 Copysecurity key to copy the security key. For more information, see Authentication and authorization.
    The External Start feature included with Nintex Workflow 2013, 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.
    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.

Disabling and enabling 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 Manage External Start page using one of the following methods. 
    • ​​Click the Settings icon on the upper right of the page, select Nintex Workflow 2013, and then select Manage External Start. 
    • On the Site Settings page, in the Nintex Workflow section, click Manage External Start.
  2. On the Manage External Start page, click Configure for the workflow of interest. 
    The Manage External Start configuration page for the selected workflow is displayed. The selected workflow is indicated in the page title. 
  3. On the Manage External Start configuration page, under the Status column for the endpoint URL of interest, select the desired status.  
  4. Click Save.

Viewing 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 Manage External Start page using one of the following methods. 
    • ​​Click the Settings icon on the upper right of the page, select Nintex Workflow 2013, and then select Manage External Start. 
    • On the Site Settings page, in the Nintex Workflow section, click Manage External Start.

Troubleshooting

External Start opti​ons not available

This section provides information for troubleshooting unavailability of External Start.

· Do you have the required license? Your license must be enabled for Enterprise Edition and Nintex Live.

· Are both Nintex Live and External Start enabled? To enable Nintex Live and External Start, go to the Central Administration Home page, click Nintex Workflow Management, click Live settings, and then click Enable for both 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 topics:
Manage External Start page
Manage External Start configuration page
​