You can use the Nintex Workflow for Office 365 REST API to import the contents of a Nintex Workflow for Office 365 export (.nwp) file into a new site workflow or list workflow on a SharePoint site. You can optionally migrate a list workflow during the import process, mapping the metadata in the export file for the list workflow to corresponding metadata on the target SharePoint list.
For more information about the REST resource used to import into a new workflow, see Import into a new workflow.
To avoid surprises while trying to import into a new workflow, take the following points into consideration:
Don't confuse this operation with the operation for importing into an existing workflow.
This operation uses the HTTP POST method, and doesn't include a workflow identifier in the URL, to import into a new workflow. The operation for importing into an existing workflow uses the HTTP PUT method and includes a workflow identifier in the URL.
If you specify a workflow identifier that doesn't exist for this operation, a new workflow is created that uses the specified identifier.
This operation creates a new workflow.
You'll get a new workflow, with a new workflow identifier that's different than the one that may be included in the export file, at the end of this operation. The response body contains the new workflow identifier, so ensure that you use that new workflow identifier when referencing the workflow later.
Note: The workflow name does not change. If you have an existing workflow in the same scope (for example, a site workflow for the same SharePoint site, or a list workflow for the same SharePoint list) that has the same name as the workflow in the export file, an error occurs.
The imported workflow is always associated with a history list and a task list.
If your export file explicitly specifies a history list or task list, the corresponding history list or task list on the target SharePoint site will be used; otherwise, the default history list or target list is used. If your SharePoint site doesn't have a default history list or default task list, the REST API creates and assigns a default history list or default task list, as needed.
If the workflow in your export file includes task forms and you want to import them, ensure that Nintex Forms integration is enabled before you import into the new workflow.
If Nintex Forms integration is enabled, the REST API imports task forms when importing into a new workflow. Otherwise, the REST API either ignores the task forms or returns an error, depending on whether you're migrating the workflow.
If you're migrating a list workflow, ensure that your SharePoint list exists.
You can either use the list information contained in the export file, or override that information by explicitly specifying the name of a SharePoint list, to map the list workflow to a corresponding list on the target SharePoint site. Either way, if the REST API can't find a corresponding list on the SharePoint site, an error occurs.
Remember to publish the new workflow.
Importing or saving into a workflow does not publish the workflow for use. If you've imported into a new workflow, you must publish the workflow to use it. You can either use the Workflow designer or the REST API to publish the workflow.
Ensure that your SharePoint authentication cookie hasn't expired.
This example avoids that issue by getting an authentication cookie from SharePoint every time you run the example, but you can cache an authentication cookie and avoid a round trip to SharePoint as long as the authentication cookie hasn't expired.
To use the example, ensure that you have the following prerequisites:
Access to a SharePoint Online site, with Manage Web permissions for the site.
An export file containing a site workflow from Nintex Workflow 2013.
Access to the Nintex Workflow for Office 365 REST API, and an API key with which to authorize the REST API. For more information, see Authentication and authorization.
Access to any version of Visual Studio 2013.
You can download the code used in this example from the following location:
Note: You need to configure the code for the example before you can build and run it. See step 4 in the following example for instructions about how to configure the code for the example.
The following example describes how to create a Visual Studio 2013 project to export a list workflow from your SharePoint Online site, by using the REST API to get the workflow definition from the site, and then importing it as a new list workflow for a specified SharePoint list on your site.
Create a new Visual Studio 2013 project, using the Console Application template for Visual C#.
Add the following references to your new Visual Studio project.
Microsoft.SharePoint.Client
Microsoft.SharePoint.Client.Runtime
System.Net
System.Net.Http
In your new Visual Studio project, paste the following code into the file named Program.cs, overwriting the existing using statements at the beginning of the file:
using System; using System.Collections.Generic; using System.Linq; using System.Threading.Tasks; using Microsoft.SharePoint.Client; using System.Security; using System.Net.Http.Headers; using System.Net.Http; using System.Net; using System.IO;
Paste the following code into Program.cs, overwriting the Main() static method already included in the Program static class, and then configure the code as described in the comments:
// The API key and root URL for the REST API.
// TODO: Replace with your API key and root URL.
static private string apiKey = "";
static private string apiRootUrl = "";
// The SharePoint site and credentials to use with the REST API.
// TODO: Replace with your site URL, user name, and password.
static private string spSiteUrl = "";
static private string spUsername = "";
static private string spPassword = "";
// The list workflow to export, and the name of the destination list for which
// the new workflow is to be imported.
// TODO: Replace with your workflow identifier and list title.
static private string sourceWorkflowId = "";
static private string destinationListTitle = "";
/// <summary>
/// The main entry point for the application.
/// </summary>
[STAThread]
static void Main()
{
// Copy a list workflow from a source list to a destination list.
CopyWorkflowToList();
}
All the configuration you need to do for this example happens here, and the code provided in subsequent steps uses these variables to get an authentication cookie from SharePoint, export the existing list workflow from the SharePoint site, and then import into a new list workflow for a different SharePoint list on your site.
Paste the following code into Program.cs, immediately after the Main static method in the Program static class:
static private string GetSPOCookie()
{
// If successful, this variable contains an authentication cookie;
// otherwise, an empty string.
string result = String.Empty;
try
{
// Construct a secure string from the provided password.
// NOTE: For sample purposes only.
var securePassword = new SecureString();
foreach (char c in spPassword) { securePassword.AppendChar(c); }
// Instantiate a new SharePointOnlineCredentials object, using the
// specified username and password.
var spoCredential = new SharePointOnlineCredentials(spUsername, securePassword);
// If successful, try to authenticate the credentials for the
// specified site.
if (spoCredential == null)
{
// Credentials could not be created.
result = String.Empty;
}
else
{
// Credentials exist, so attempt to get the authentication cookie
// from the specified site.
result = spoCredential.GetAuthenticationCookie(new Uri(spSiteUrl));
}
}
catch (Exception ex)
{
// An exception occurred while either creating the credentials or
// getting an authentication cookie from the specified site.
Console.WriteLine(ex.ToString());
result = String.Empty;
}
// Return the result.
return result;
}
The GetSPOCookie static method uses the SharePoint site and credentials that you configured in step 4 to get an authentication cookie from SharePoint.
Paste the following code into Program.cs, immediately after the code you pasted in the previous step:
static async private void CopyWorkflowToList()
{
// Create a new HTTP client and configure its base address.
HttpClient client = new HttpClient();
client.BaseAddress = new Uri(spSiteUrl);
// Add common request headers for the REST API to the HTTP client.
client.DefaultRequestHeaders.Accept.Add(
new MediaTypeWithQualityHeaderValue("application/json"));
client.DefaultRequestHeaders.Add("Api-Key", apiKey);
// Get the SharePoint authorization cookie to be used by the HTTP client
// for the request, and use it for the Authorization request header.
string spoCookie = GetSPOCookie();
if (spoCookie != String.Empty)
{
var authHeader = new AuthenticationHeaderValue(
"cookie",
String.Format("{0} {1}", spSiteUrl, spoCookie)
);
// Add the defined authentication header to the HTTP client's
// default request headers.
client.DefaultRequestHeaders.Authorization = authHeader;
}
else
{
throw new InvalidOperationException("Cannot define Authentication header for request.");
}
// If we're at this point, we're ready to make our request.
// Note that we're making this call synchronously - you can call the REST API
// asynchronously, as needed.
// First, we'll export the workflow from the source list.
var exportWorkflowUri = String.Format("{0}/api/v1/workflows/packages/{1}",
apiRootUrl.TrimEnd('/'),
Uri.EscapeUriString(sourceWorkflowId));
HttpResponseMessage exportResponse = client.GetAsync(exportWorkflowUri).Result;
// If we're successful, import the exported workflow to the destination list, as a new workflow.
if (exportResponse.IsSuccessStatusCode)
{
// The response body contains a Base64-encoded binary string, which we'll
// asynchronously retrieve as a byte array.
byte[] exportFileContent = await exportResponse.Content.ReadAsByteArrayAsync();
// Next, import the exported workflow to the destination list.
var importWorkflowUri = String.Format("{0}/api/v1/workflows/packages/?migrate=true&listTitle={1}",
apiRootUrl.TrimEnd('/'),
Uri.EscapeUriString(destinationListTitle));
// Create a ByteArrayContent object to contain the byte array for the exported workflow.
var importContent = new ByteArrayContent(exportFileContent);
// Send a POST request to the REST resource.
HttpResponseMessage importResponse = client.PostAsync(importWorkflowUri, importContent).Result;
// Indicate to the console window the success or failure of the operation.
if (importResponse.IsSuccessStatusCode)
{
Console.WriteLine("Successfully imported workflow.");
}
else
{
Console.WriteLine("Failed to import workflow.");
}
}
}
The CopyWorkflowToList static method uses an HTTP client to invoke the REST resource provided by the REST API to first export your list workflow from your SharePoint site. The client's default request headers are configured, the GetAsync method is used to invoke the REST resource, and, if successful, the response is written to an export file.
Then, the same HTTP client is used to import the contents of the export file into a new list workflow for the specified SharePoint list. A ByteArrayContent object is used to encapsulate the binary contents of the export file, and the PostAsync method is used to invoke the REST resource.
Build and run the Visual Studio project.
If you've configured the variables provided in step 4 appropriately, running the project produces a copy of the specified list workflow associated with the specified SharePoint list on your SharePoint site.
Note: The workflow name does not change. If you already have a list workflow for the specified SharePoint list with a name that matches the name of the exported workflow, an error occurs.