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.
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 information 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
- 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.
- 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.
- 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.
- (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
- 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.
- 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.
- 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
- 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.
- 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.
- 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.
- In the View details dialog box, click Copy URL to copy the endpoint URL.
Example endpoint URL: https://run.nintex.io/x-start/weuyj1TkGD
- In the external service configuration, paste the copied endpoint URL.
- In the View details dialog box, click Copy security key to copy the security key. For more information, see the Authentication and authorization section given below.
- 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. For more information about using External Start with external services such as Zapier or Azuqua or with a code-based solution, see the following page on Nintex Connect: https://community.nintex.com/docs/DOC-3167.
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
: - Concatenate a delimited string, using a colon (:) character as the delimiter, from the HTTP method name, endpoint URL, nonce, timestamp, and request body.
- Encode the string in UTF-8 format.
- Encode the security key in UTF-8 format.
- 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("-", "");
}
}
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
- 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.
- 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.
- On the Manage External Start configuration page, under the Status column for the endpoint URL of interest, select the desired status.
- 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 options not available
This section provides information for troubleshooting unavailability of External Start.