Nintex - Component workflow

Caution: Regenerating a token replaces the current active token, which will be invalid in 24 hours. Regenerating a token that is revoked or expired will make the component workflow become available for external start again. Ensure to update the external workflows or applications that call the component workflow with the new token, or else they will fail.

1. Go to Settings > Environment > Component workflow tokens.

2. On the left menu, click Component workflow tokens. Component workflows that are close to expiring will have a warning icon and workflows that have already expired will have a red error icon appearing against the workflow name to make them easily identifiable.

3. To the right of the name of the component workflow, click and then select API endpoints.

   Note: Alternately, you can open the component workflow dialog from the Workflows page. Click (Options) next to the name of the component workflow, and then select API endpoints.

4. Click next to the Token field and select Regenerate.
5. Click Regenerate to confirm.

The token becomes regenerated and the component workflow is valid for external start again.

6. Update the new regenerated token in your application to complete the process.

Caution: Regenerating a token replaces the current active token, which will be invalid in 24 hours. Regenerating a token that is revoked or expired will make the component workflow become available for external start again. After the token is regenerated, you must update the external workflows or applications that call the component workflow with the new token.

1. Go to Workflows > All workflows.

2. To the right of the name of the component workflow, click and then select API endpoints.

3. Click next to the Token field and select Regenerate from the menu.
4. Click Regenerate to confirm.

The token is regenerated and the component workflow is valid for external start again.

1. Open the Nintex Workflow product of choice.
2. Design the parent workflow that will call your Component workflow.
3. In the Workflow designer of the parent workflow, add the appropriate action:
   

   For this product...	Use this action:
   Nintex Workflow	Call a workflow (same tenancy) Call a web service (different tenancy)
   Nintex for SharePoint 2019 or Subscription Edition	Start workflow in Nintex Workflow
   Nintex for SharePoint 2016 and 2013	Start workflow in Nintex Workflow

4. Configure the URL of the action to use the Component workflow's URL.
View API endpoints of the Component workflow via Environment page

1. Go to Settings > Environment > Component workflow tokens.

2. On the left menu, click Component workflow tokens.

3. To the right of the name of the component workflow, click and then select API endpoints.

4. In the new window that appears, to the right of the credential you want to copy, click Copy.

View API endpoints of the Component workflow via Workflows page

1. Go to Workflows > All workflows.

2. To the right of the name of the component workflow, click and then select API endpoints.

3. In the new window that appears, to the right of the credential you want to copy, click Copy.

5. Configure the start variables.

6. Publish the parent workflow.

   The Component workflow runs when called by the parent workflow during execution.

You can start your Component workflow from any service or application that can:

• Make POST calls to HTTPS endpoints.
• Send a request payload in the body with a content-type of application/json.

Note: If your application or service can consume OpenAPI Specifications, you can import the specification of the Component workflow using the OpenAPI Specification URL. Go to Settings > Environment > Component workflow tokens and click next to the Component workflow to find the OpenAPI Specification URL.

1. Find the Component workflow's API endpoints window.
View API endpoints of the Component workflow via Environment page

1. Go to Settings > Environment > Component workflow tokens.

2. On the left menu, click Component workflow tokens.

3. To the right of the name of the component workflow, click and then select API endpoints.

4. In the new window that appears, to the right of the credential you want to copy, click Copy.

View API endpoints of the Component workflow via Workflows page

1. Go to Workflows > All workflows.

2. To the right of the name of the component workflow, click and then select API endpoints.

3. In the new window that appears, to the right of the credential you want to copy, click Copy.

2. Copy the URL with token and configure your application to make a POST request using this URL.
3. Copy the Request body to copy the Component workflow request payload template. Configure your application to submit a JSON request body with the start variables.
4. If you want the Component workflow to call another endpoint when the workflow completes, configure the callbackURL field in the request payload. All callback URLs are sent as HTTPS POST.

Note:  The Component workflow endpoint returns only the workflow ID of the called workflow. If you want to retrieve data from the completed workflow, you must accept it via a callback URL.

Example of a request body

This request includes two start variables (first name and last name) and a callback URL.

{
  "startData": {
    "se_firstname_11": "John",
    "se_secondname_21": "Smith",
  },
  "options": {
    "callbackUrl": "https://callbackurl.com"
  }
}

Example of a callback post body

The request sent to the callback URL includes:

• Workflow information
• Start variables (prefixed with se)
• Workflow variables that were designated as 'output' variables in the workflow design (prefixed with c).

{
  "returnData":{              
    "c_status":"Review",  
    "se_firstname_11":"John",
    "se_secondname_21":"Smith"
  },
  "workflow": {
    "id":"a58a5b90-eda6-41af-8acb-00fe299c68a6",
    "name":"Sample workflow",
    "publishedId":"3cace836-0323-4f79-b56f-5480bf79aab7"
  }
}

Note:  To upload files to your workflow, you must have created a collection start variable in the Component workflow to hold the uploaded files.

To start a workflow that requires a file upload, you must make three sequential API calls:

1. Create a paused instance of the Component workflow.

   Nintex Workflow returns an instance token to identify the paused instance.

2. Upload each required file using the instance token.

   Nintex Workflow returns a file upload token to identify the uploaded file.

3. Start the paused instance using the instance token and file upload tokens.

Note: The instance token and file upload tokens are separate from the authentication token, which allows you to make the call to the specific workflow. Each API call must also include the authentication token in the query: https://<TenantName>.workflowcloud.com/api/v1/workflow/published/<WorkflowID>?token=<Token>

To start a workflow with files:

1. Find the base URL and token for your Component workflow endpoints

   In Nintex Workflow:

   1. Find the API endpoints of the Component workflow:
   View API endpoints of the Component workflow via Environment page

   1. Go to Settings > Environment > Component workflow tokens.

   2. On the left menu, click Component workflow tokens.

   3. To the right of the name of the component workflow, click and then select API endpoints.

   4. In the new window that appears, to the right of the credential you want to copy, click Copy.

   View API endpoints of the Component workflow via Workflows page

   1. Go to Workflows > All workflows.

   2. To the right of the name of the component workflow, click and then select API endpoints.

   3. In the new window that appears, to the right of the credential you want to copy, click Copy.

   2. In the Component workflow dialog box, to the right of URL with token, click Copy.
   3. Use the URL from the https:// to /instances as the base URL.
      

      https://<TenantName>.workflowcloud-test.com/api/v1/workflow/published/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/instances?token=vvvvv

   4. Use everything after token= as the authentication token.
      

      https://<TenantName>.workflowcloud-test.com/api/v1/workflow/published/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/instances?token=vvvvv

2. Send a POST request with the content-type of application/json to /create.
   

   https://<TenantName>.workflowcloud.com/api/v1/workflow/published/<WorkflowID>/instances/create?token=<Token>

cURL example:

curl -s -w '\n' -i -X POST \ 
'https://<TenantName>.workflowcloud.com/api/v1/workflow/published/<WorkflowID>/instances/create?token=<Token>'

3. Store the instance token that is returned.
4. For each file:
   1. Send a POST request with a single file, filename and the instance token to /uploads.
      

      https://<TenantName>.workflowcloud.com/api/v1/workflow/published/<WorkflowID>/instances/uploads?token=<Token>

      Note: Nintex Workflow does not support requests that contain both a Content-Length header and a Transfer-Encoding: chunked header. Requests that contain these headers together will be rejected with a 400 Bad Request response.

      cURL example:

      curl -s -w '\n' -i -X POST \
      'https://<TenantName>.workflowcloud.com/api/v1/workflow/published/<WorkflowID>/instances/uploads?token=<Token>'\
      -H 'Content-Type: multipart/form-data' \ 
      -H 'Transfer-Encoding: chunked' \ 
      -F 'File-Name=<UploadedFileName>' \ 
      -F 'Instance-Token=<InstanceToken>' \ 
      -F 'File=@<PathToFile>'

      C# example

      
      using (var client = new ExternalHttpClient())  {
        client.DefaultRequestHeaders.TransferEncoding.Add(new System.Net.Http.Headers.TransferCodingHeaderValue("chunked"));
        client.DefaultRequestHeaders.TransferEncodingChunked = true;
        foreach (var file in files) {
          using (var content = new MultipartFormDataContent("Upload----" + DateTime.Now.ToString(CultureInfo.InvariantCulture)))  {
            content.Add(new StringContent(instanceToken), "Instance-Token");
            content.Add(new StringContent(file.Key), "File-Name");
            content.Add(new StreamContent(new FileStream(file.Value, FileMode.Open, FileAccess.Read)), "File", file.Key);
            using (var response = client.PostAsync(endpoint, content).Result)  {
              //Store the file upload token from the response.
            }
          }
        }
      }

   2. Store the file upload token that is returned.
5. When all files have been uploaded, send a POST request with the workflow start payload as a JSON object, including the instance token and all file tokens, to the base URL.
   

   https://<TenantName>.workflowcloud.com/api/v1/workflow/published/<WorkflowID>/instances?token=<Token>

   Note:  The Component workflow endpoint returns only the workflow ID of the called workflow. If you want to retrieve data from the completed workflow, you must include a callback URL in the request payload.

   cURL example:

   curl -s -w '\n' -i -X POST \
   'https://<TenantName>.workflowcloud.com/api/v1/workflow/published/<WorkflowID>/instances?token=<Token>'
   -H 'Content-Type: application/json' \
   -d '{"startData": {"se_files1": "<FileUploadUrl>"}, "options": {"instanceToken": "<InstanceToken>"}}'