mattbriggs

Export and Publish Nintex Workflow with the SOAP Web Service

Blog Post created by mattbriggs Employee on Oct 7, 2016

You can use a Windows Communication Foundation (WCF) client to hit the Nintex Workflow SOAP endpoints. With Visual Studio, you can add the Nintex service as a resource and then build a client. In this post, I show you how to add the resource, create your client, configure your bindings, and then use the export and publish endpoints to retrieve a workflow file and add one to an existing SharePoint list.

 

In this post we will walk through building a client from scratch. Visual Studio will help with the behind the scenes code to build the proxy and client. You can also download the complete project from the Nintex Platform SDK.

This is what might be called a beta topic. I'm looking for feedback on how to make this subject clearer and more useful to you. Please feel free to send me your feedback or include your feedback as comments to this post. Thanks, Matt

Table of Contents

 

Export and publish a workflow overview

The following lists covers the major steps for creating a SOAP client, bounding to the endpoints, and then interacting with the Nintex Workflow resources. After the list, you can find more detailed explanations of each of the steps.

To export and publish a Workflow

  1. Create the console application Visual Studio.
  2. Add the service reference to: http://yoursite/_vti_bin/NintexWorkflow/Workflow.asmx
  3. Add the service dependency from the object browser for the service reference, such as, WorkflowWCFExport.ServiceReference1;
  4. Update app.config for the binding and the security mode.
  5. Add variables for the source workflow name, the source list name, the target list, the account user name, and account password.
  6. Instantiate the SOAP client. You will want to specify the binding name for the client, for example, name="NintexWorkflowWSSoap1".
  7. You will use the export workflow endpoint which renders the workflow as a string. You can save this string to your desktop, or you can upload it, as per the sample to target list using the PublishFromNWFXml endpoint.

 

Create the console application

You can use Visual Studio to create your application.

To create the console application

  1. Open Visual Studio.
  2. Create a console application by selecting File and then New, and then under the Visual C# group, selecting Console Application.
  3. Name your application and solution. Click OK.

In the solution, you will add a service reference and point to the Nintex Workflow web services endpoint that contains a list of the available resources. Visual Studio will add the proxy code, and you will create a SOAP client using the Nintex NintexWorkflowWSSoapClient class.You can find more information about using Windows Communication Foundation Services with Visual Studio at MSDN. In addition, you will need to update the bindings which are configured in the app.config file. Here is an image of a solution file for working with the service:

Add the service reference

You can use Visual Studio to add the reference to the Nintex Workflow services. Visual Studio will add the code that will enable you to instantiate the SOAP client. The following image shows the Add Service Reference window that opens when you add the service to your project. You can find the service at: http://yourserver/_vti_bin/NintexWorkflow/Workflow.asmx.

To add the service reference

  1. Right-click the Services References folder in the Solution Explorer, and select Add Services References. Note, you can also add the reference by right-clicking the References group and making your selection.
  2. Add the Nintex Workflow SOAP service end point to the Address box. It is:
    http://yourserver/_vti_bin/NintexWorkflow/Workflow.asmx and click Go.
  3. Click OK. The Service under the service namespace will be added to the Service Reference folder.

 

Add the service dependency

You will need to add the service dependency to your class. The following image shows the Object Browser. You can find the reference under the name of your project.

To add the service dependency

  1. Right click the service reference, and then select View in Object Browser.
  2. Select the namespace and name of the service references and add to the dependencies section of the Program.cs file in the console application. In this sample, I added using WorkflowWCF.ServiceReference1;

Code

using System;
using System.IO;
using System.Security.Principal;
using System.Text;
using WorkflowWCF.ServiceReference1;

Update app.config

Update the configuration file (app.config) to set your binding settings. The binding contains parameters specified as attributes of the binding element. In addition in the security group, you will need to specify the mode as TransportCredentialOnly. When you instantiate the SOAP client, you will specify the name of the binding. For instance in this example, NintexWorkflowWSSoapClient soapClient = new NintexWorkflowWSSoapClient("NintexWorkflowWSSoap")

specifies the NintexWorkflowWSSoap binding indicated by the attribute name in the binding element.

To update app.config

  1. Add the binding selection (below) into the basicHttpBinding element.
  2. Note the name of your binding. In this example, the name is NintexWorfklowWSSoap.

Code

<binding name="NintexWorkflowWSSoap" closeTimeout="00:01:00" openTimeout="00:01:00" 
receiveTimeout="00:10:00" sendTimeout="00:01:00" allowCookies="false"
bypassProxyOnLocal="false" hostNameComparisonMode="StrongWildcard"
maxBufferSize="100000000" maxBufferPoolSize="100000000"
maxReceivedMessageSize="100000000" messageEncoding="Text" textEncoding="utf-8"
transferMode="Buffered" useDefaultWebProxy="true">

    <readerQuotas maxDepth="32" maxStringContentLength="999999999" maxArrayLength="16384"
maxBytesPerRead="4096" maxNameTableCharCount="16384" />

    <security mode="TransportCredentialOnly">
        <transport clientCredentialType="Ntlm" proxyCredentialType="None" realm="" />
        <message clientCredentialType="UserName" algorithmSuite="Default" />
    </security>
</binding>

 

Add variables

Add the variables you will use to work with the endpoint to the class. Identify the pieces of information you need to interact with the endpoint. In the code sample, you are publishing to the workflow named workflowpublishformsource.

Code

var workflowName = "PublishFormXMLtoTarget"; // 
var sourceListName = "workflowpublishformsource"; //
var workflowfile = "";
var targetlistname = "RecieveWorkflow";
var fullFilePath = @"C:\out\exportworkflow.nwf";

Instantiate the SOAP client

With the service references, you can access the NintexWorkflowWSSoapClient. Instiate the SOAP client, and then add your user name, password, domain. In addition you can specify NTLM and allow for impersonation.

Code

soapClient.ClientCredentials.Windows.ClientCredential.UserName = "username";
soapClient.ClientCredentials.Windows.ClientCredential.Password = "password";
soapClient.ClientCredentials.Windows.ClientCredential.Domain = "domain";
soapClient.ClientCredentials.Windows.AllowNtlm = true;
soapClient.ClientCredentials.Windows.AllowedImpersonationLevel = TokenImpersonationLevel.Impersonation;

To use the service over an HTTPS connection, you will need to change the endpoint to an HttpsTransportBindingElement.

Use the end points

You can specify the specific endpoint using the SOAP client object. In this example, you are retrieving the workflow and assigning to the workflow file string variable.

For more information on the available Nintex Workflow endpoints you can check out the SDK. See Service operations.

Code

var retrieved = getWorkflow(soapClient, workflowName, sourceListName, workflowfile, fullFilePath);
var copied = CopyListWorkflow(soapClient, workflowName, sourceListName, targetlistname);

getWorkflow() method

This method uses the ExportWorkflow endpoint. You can see the code sample below for an example of how you can use the endpoint. Refer to the API documentation for more information about the endpoint.

Code

public static bool getWorkflow(NintexWorkflowWSSoapClient soapClient, string workflowName, string sourceListName,
            string workflowfile, string fullFilePath)
        {
            try
            {
                workflowfile = soapClient.ExportWorkflow(
                    workflowName,
                    sourceListName,
                    "list"
                );

                Console.Write(workflowfile);
                Console.Write("\ngetWorkflow: success\n");
                File.WriteAllText(fullFilePath, workflowfile, Encoding.Unicode);
                return true;
            }
            catch (Exception ex)
            {
                Console.Write(ex.ToString());
                Console.Write("\ngetWorkflow: fail\n");
                return false;
            }
        }

CopyListWorkflow() method

This method export a workflow file using the ExportWorkflow endpoint. And then the method changes the name to name and the string "_Copy2." The method then posts the file to a new workflow file using the PublishFormNWXML. For more informaiton about this endpoint, see the API documentation.

Code

        public static bool CopyListWorkflow(NintexWorkflowWSSoapClient soapClient, string workflowName,
            string sourceListName, string targetListName)
        {
            // Export the workflow from the source list to a StringBuilder object, and then
            // import the workflow from the StringBuilder object to the target list.
            try
            {
                // First, export the workflow to a StringBuilder object.
                var sb = new StringBuilder(
                    soapClient.ExportWorkflow(
                        workflowName,
                        sourceListName,
                        "list")
                );

                Console.Write("\nCopyListWorkflow: export success\n");

                // Now, import the workflow from the StringBuilder object. The PublishFromNWFXml
                // service operation is configured so that it does not save the workflow
                // if the workflow cannot be published.
                if (sb.Length > 0)
                    return soapClient.PublishFromNWFXml(
                        sb.ToString(),
                        targetListName,
                        workflowName + "_Copy2",
                        true);
               
                Console.Write("\nCopyListWorkflow: copy success\n");
                return true;
            }
            catch (Exception ex)
            {
                Console.Write(ex.ToString());
                Console.Write("\nCopyListWorkflow: fail\n");
                return false;
            }
        }

And that is it. I hope you can explore some of the other end points in your reference. Thanks!

Outcomes