Capturx for SharePoint 2.0: Notification Workflows

Transcription

1 Capturx for SharePoint 2.0: Notification Workflows 1. Introduction The Capturx for SharePoint Notification Workflow enables customers to be notified whenever items are created or modified on a Capturx Forms list. This workflow provides for automatic notification and data transfer to be initiated as a response to ink uploads, edits to a form, or form approvals. The notification is based on simple REST 1 (Representational State Transfer) calls to an endpoint provided by the customer. Querystring parameters identify the IDs of the list and the item that has been uploaded, modified and approved. In scenarios in which a small amount of data is transmitted, the Capturx Notification Workflow provides the means for additional column values to be transmitted as part of the REST call. For larger volumes of data, the SharePoint web service API can be employed by the receiving endpoint to retrieve the desired data as XML. If you will Step-by-Step Instructions You need to Install This section guides you through the process of configuring the Notification Workflow for any SharePoint list (works for any list, not just for Capturx lists). 1. Select the list settings menu (only available to administrators) under List tab 2. Select Workflow settings 1

2 for SharePoint 3. Configure Standard Workflow parameters a. Select the NotificationWorkflow b. Give it a Name c. Check the Start this workflow when an item is changed d. DO NOT check Start workflow when a new item is created Capturx inserts blank rows at print time. These rows are then updated when ink uploads take place. Causing the workflow to trigger on creation will result in blank values being transmitted to the associated REST endpoint. e. Click Next 4. Notification Workflow Settings sales@adapx.com 2127 Fifth Avenue Seattle, WA

3 a. Notification Endpoint The customer needs to expose a REST endpoint in their DMZ (endpoint needs to be accessible from the Internet). REST is a very simple technology. Basically the request URL contains all of the data as query string parameters (underlined in the example below), e.g.: A REST endpoint can also be implemented in Perl, PHP, Python or any other web technology able to respond to an HTTP 1.0/1.1 web request. Here s an example of one that returns keys passed: using System; using System.Collections.Generic; using System.Linq; using System.Web; using System.Web.UI; using System.Web.UI.WebControls; using System.Text; public partial class Keys : System.Web.UI.Page { } protected void Page_Load(object sender, EventArgs e) { } StringBuilder sb = new StringBuilder(); Response.Flush(); foreach (string key in Request.QueryString.AllKeys) { } sb.appendformat( {0}, key); Response.Write(sb.ToString()); If the customer is not using the View mechanism described below, then they will use the listpath and itemid parameters passed into the REST endpoint to retrieve the FS item. Capturx for SharePoint v 2.0 provides an XML extraction service that can be used to retrieve all field data of a form instance. The following code snippet illustrates the use of the service (please see Appendix A for the full sample REST endpoint code): // Build URL and invoke endpoint string url = siteurl + /_layouts/capturx/exportfile.aspx? + ItemId= + Request.QueryString[ itemid ] + &ListId= + targetlistguid + &ExportType=XML ; WebClient wc = new WebClient(); wc.credentials = creds; byte[] content = wc.downloaddata(url); // Convert to string System.Text.Encoding encoding = new System.Text.UTF8Encoding(); String encodedxml = encoding.getstring(content);

4 Besides using the service as discussed above, data that is stored in SharePoint columns can be retrieved as usual via the standard Lists.asmx 2 web service. See Appendix B for sample code using this approach. This approach is limited to retrieval of the data mapped to SharePoint columns, which is limited by SharePoint That makes this method less convenient, particularly for forms that may contain a large number of fields. b. Credentials If needed, enter username, password and domain information to access REST endpoint. This should be provided by customer s network administrator. c. Launch Condition Configuring launch condition for the following scenarios: Executing Notification workflow when ink is uploaded With CFS 2.0, list items are created at time of print with default status Printed. When ink is uploaded, list item status changes to Imported. To setup workflow to trigger on ink upload, launch condition should be set with Status = Imported Note: If forms are printed with CFS 1.6, list items will not be created until ink upload, but default status will remain Imported after ink upload. Executing notification workflow when list item is approved To execute notification workflow for only when status of list item has changed to Approved, set launch condition to Status = Approved. Executing the workflow when list item is updated To execute workflow when any changes have been made to the list item, including manual edit/save, ink upload, or any status changes, the Launch condition Column and Value fields should be left blank. This will use SharePoint s built in workflow trigger condition. 2

5 d. View In addition to enabling the customer to retrieve their data via callback, this Notification Workflow can be configured to pass selected form field values as part of the REST call immediately. This alleviates the need to write code to access the SharePoint Lists.asmx web service, hence greatly simplifying the coding task. SharePoint list views are a way to select one or more columns to be displayed in the default view for a list (selected via dropdown control in the upper-right corner of the list control). If the user defines a public view (personal views are not allowed) then it can be selected when configuring the Notification Workflow. Once configured, every REST call is augmented with key/value pairs representing the column name and current column value for the updated item: astname=smith&quantity=5 (This example assumes that the customer has defined a view with the FirstName, LastName, and Quantity columns). NOTE: the number of fields in the view should be less than or equal to 128. REST is also restricted in terms of overall message sizes. Even if fewer than 128 items are included, the resulting message may exceed the limit imposed by some servers. In this case, a 404 error is returned. If you suspect that you might encounter these practical limits, we recommend that you don t use View Feature and instead use the list URL and item ID parameters to retrieve your data using the SharePoint Lists.asmx web service. For an introduction, please see: getlistitems(v=office.12).aspx. e. Token The customer can optionally select a list column (not a Capturx column) to store any item-specific information. This information is set by whatever string the REST call is returning. For example, the column could contain the database item identifier in the customer s back-office database. This parameter is passed along in subsequent REST calls (when the item is updated) and can be used to update the appropriate database item in the customer s back-office database.

6 3. Testing Now you are ready to test your workflow. If the REST endpoint specified above is accessible, you can do the following: a. Create a new item b. Edit the item and click Ok to save the changes Your REST endpoint should now be called using the provided credentials. If you have selected a Token column, then you should see your return value contained in that column. If any error occurred, then your workflow status would indicate that. To try again, you will have to clear the workflow status (by clicking on the column and then terminating the currently running workflow for this item). 4. Best Practices Rerun Failed Workflows During operations, the targeted REST endpoint may become unavailable. This will cause the workflow to enter an error state, represented as Error Occurred in the status field. Therefore, it is advisable to either periodically, or at startup time of the REST service, to do the following: 1. Query the list for any item where the status indicates an error ( Error Occurred ). 2. For each such item, modify one of the properties programmatically (using the Lists.asmx web service). The second step will invoke the workflow again on the changed item which will call the REST endpoint again. As an alternative, the workflow can be manually restarted via SharePoint s item menu actions. See Appendix A for Sample REST endpoint that extracts a form instance s XML using the Capturx ExportFile.aspx service See Appendix B for Sample REST endpoint that extracts SharePoint column data as XML using the standard SharePoint Lists.aspx web service. Access Appendix A and B at the following link: Adapx. All rights reserved. Capturx works with digital pens from Anoto. This document is for informational purposes only. Features and specifications are subject to change. Adapx and Capturx are either registered trademarks or trademarks of Adapx in the United States and/or other countries. All other trademarks are the property of their respective owners.