GlobalConnections for Microsoft SharePoint and OneDrive Guide

Transcription

1 GlobalConnections for Microsoft SharePoint and OneDrive Guide 127 Church Street, New Haven, CT O: (203) E: Square 9 Softworks Inc. 127 Church Street New Haven, CT (+1) education@square-9.com

2 2 GlobalConnections for SharePoint and OneDrive GlobalConnections for Microsoft SharePoint and OneDrive Guide

3 GlobalConnections for Microsoft SharePoint and OneDrive Guide Version 2.0 Copyrights, Legal Notices, Trademarks, and Servicemarks Copyright 2017 Square 9 Softworks All rights reserved. No part of this work may be reproduced or transmitted in any form or by any means whatsoever, without written permission of Square 9 Softworks unless such copying is expressly permitted by Federal copyright law. For information regarding permissions, contact: Square 9 Softworks Inc., 127 Church Street, New Haven, CT 06510, USA, info@square-9.com. June 2017 edition Publication subject to change without notice, Square 9 Softworks assumes no liability for any damages incurred directly or indirectly from errors, omissions, or discrepancies between the actual software you install and/or the contents of this publication or any other accompanying publication. GlobalSearch, and GlobalForms are registered trademarks of Square 9 Softworks. All other products and devices listed in this document are trademarks or registered trademarks of their respective companies and are hereby acknowledged. Microsoft, SharePoint, OneDrive, and Windows are trademarks and service marks of Microsoft, Inc., registered in the United States and other countries, and are the property of Microsoft, Inc. Square 9 Softworks Inc. 127 Church Street New Haven, CT (+1) education@square-9.com

4

5 Table of Contents GlobalConnections for SharePoint & OneDrive... 1 Overview... 1 Prerequisites... 2 Install Connector and SharePoint Client... 2 Configure SharePoint or OneDrive... 3 Base Path Location... 3 File Names Posted to SharePoint or OneDrive... 3 File Uploads to SharePoint or OneDrive... 4 View GlobalCapture Console... 4 Configure Workflow... 5 Create Workflow... 5 Configure Release... 8 Help and Support Support Phone: , option 2 support@square-9.com Other Resources Forums: forums.square-9.com Square 9 classes: education@square-9.com GlobalConnections for Microsoft SharePoint and OneDrive Guide Table of Contents i

6

7 GlobalConnections for SharePoint & OneDrive Designed as part of your total enterprise content management (ECM) solution, the GlobalConnections for Microsoft SharePoint and OneDrive from Square 9 Softworks allows you to automatically release captured data and documents directly from the power of GlobalCapture to the convenience of SharePoint or OneDrive for Business from Microsoft. GlobalConnections for Microsoft SharePoint and OneDrive will work with: GlobalCapture, GlobalCapture Convey, and GlobalCapture Convey PLUS, versions 2.0 and later. SharePoint 2013, SharePoint Server 2016, and SharePoint Online. OneDrive for Business. With the connector, you can create GlobalCapture Fields and Workflows as usual and then release them to SharePoint or OneDrive for Business by adding Workflow settings and a configuration XML file generated by the connector. To do so, you will need to install a Microsoft SharePoint Client and the connector, configure your Workflow, configure the connector using the provided utility, and put the resulting XML file in you GlobalCapture instance. Overview 1. Install your connector and SharePoint client media. 2. Configure SharePoint. 3. Create your GlobalCapture Workflow to release locally, test it, and then unpublish it. 4. Edit the Workflow for release to SharePoint or OneDrive: a. Add a Set Process Field Node, set its value to SPXML_<YourMappingFileNameHere>.xml and make note of this filename. b. Replace your temporary Release Node with a Call Assembly Node which includes the path to the connector DLL file (Square9.O365Connect.dll). c. Optionally, for troubleshooting, add a Set Process Field Node, set its value to the S9 Notation {PROCESSID} and make note of its Process Field ID number. d. Complete the connections, but do not publish the Workflow. 5. Configure the connector: a. Run the Square9.O365Config.exe file to launch the configurator utility. b. Configure the settings according to your SharePoint instance. c. Set credentials for your SharePoint or OneDrive user and click Test. d. Configure System settings, adding the Process Field ID number (if used) and a File Name Field ID ( -4, if you are using the original file name). e. Set Field Mappings, entering the Process Field ID number of each Field to be sent to SharePoint and its corresponding Process Field/SharePoint field name. f. Save the settings to generate an XML file, giving it the same name as in Set Process Field Node. 6. Publish the Workflow and run it. GlobalConnections for SharePoint and OneDrive GlobalConnections for SharePoint and OneDrive 1

8 Prerequisites To release data and documents from GlobalCapture, you will need to configure your SharePoint or OneDrive instance with a Document Library (which requires administrator permissions), your Call Assembly Node in a GlobalCapture Workflow (which requires administrator permissions and a Designer license), and your connector. Before configuration, ensure that: The machine running the SharePoint release has the SharePoint client components installed. You know the web URL of the base endpoint for your SharePoint or OneDrive site. When choosing OneDrive as your release target, the base path must target the Documents list. You know the URL of the destination folder in the SharePoint OneDrive site that the captured documents will be released to. You know the name of the domain of the user you will use to authenticate to SharePoint or OneDrive for Business. You know the username and password of a SharePoint user or OneDrive with appropriate permissions to create objects within the SharePoint or OneDrive folders. You are logged into GlobalCapture using an administrator user account and a GlobalCapture Designer license. Tip: Key SharePoint Definitions. List Where data items are stored, displayed, and shared in SharePoint. Document Library Where documents are stored, displayed, and shared in SharePoint. Libraries are a type of SharePoint List and are similar to folders containing documents and other content. You can create multiple Document Libraries, with your choice of Document Templates. Column Where you organize and track information in a List or Library. Site A collection of SharePoint lists, libraries, and pages, which are based on a site template. Repository A version-controlled SQL Server database where all the SharePoint content lives. Install Connector and SharePoint Client GlobalConnections for Microsoft SharePoint and OneDrive is distributed through download links. These links can be obtained from the Square 9 Softworks Fulfillment department by contacting them at: Phone Option 1 fulfillment@square-9.com Once the link is sent, it is valid for seven days. Download the installation media to a folder of your choice. You must have system administrator permissions to perform the installation procedures. 1. Copy the following files to the GlobalCapture Engine directory: Square9.O365Connect.dll The main application assembly. Square9.O365Config.exe The configuration utility that will allow an administrator to map GlobalCapture Process Fields to a SharePoint or OneDrive repository. The default location is C:\GetSmart\CaptureServices\GlobalCapture_1. 2 GlobalConnections for SharePoint and OneDrive GlobalConnections for Microsoft SharePoint and OneDrive Guide

9 2. Run the sharepointclientcomponents_ _x64-en-us.msi SharePoint Client Components installer, following Microsoft instructions. (Refer to your Microsoft documentation for details.) Configure SharePoint or OneDrive A static SharePoint or OneDrive for Business user is required to send data and documents into them. Permissions must be set in SharePoint or OneDrive to allow data and documents to be added from GlobalSearch to a Document Library. (Please refer to Microsoft SharePoint and OneDrive documentation for details.) Each GlobalCapture Workflow can use a common SharePoint or OneDrive user, or a different user may be specified for each Workflow/release point. Cached passwords are stored with 256-bit encryption. One GlobalCapture instance can release to multiple instances of SharePoint or OneDrive. Additionally, if multiple instances are used, they can be of mixed types (SharePoint Online, OneDrive, or SharePoint installed on a local server or private cloud). 1. Configure SharePoint or OneDrive for your release. 2. Make note of the field names and the SharePoint or OneDrive base path location; you will need them to complete the release. Base Path Location A base path location must exist in SharePoint or OneDrive and must be specified. Optionally, a child folder of the base path may be dynamically set and/or automatically created, if it does not exist, based on a field value provided by GlobalCapture. For example, if your base path was /APInvoices/2017, you could automatically create a subfolder for Vendor Name when required, which will result in the storage location /APInvoices/2017/Square9. CAUTION: With Dynamic folder inspection and creation in SharePoint, real time / unattended folder creation can result in large numbers of unintended folders getting created and there is also significant latency introduced into the release process. Dynamic folder creation checks can make the release process take 10 to 20 times longer than without this feature enabled. This is especially apparent when using SharePoint Online versions. File Names Posted to SharePoint or OneDrive As a Microsoft system requirement, file names posted to SharePoint and OneDrive must be unique. In SharePoint, a file s saved name is stored in the default Name column. You can use a GlobalCapture Process Field to name a file in SharePoint or OneDrive, if you wish. If an attempt is made to store a file that is not unique, the GlobalCapture release will automatically append an underscore and a sequential number to the end of the file to make it unique. GlobalCapture does allow you to use the file s original name prior to capture, if desired. GlobalConnections for SharePoint and OneDrive GlobalConnections for SharePoint and OneDrive 3

10 File Uploads to SharePoint or OneDrive A typical file upload to SharePoint will normally take one to three seconds (on premise), but depending on latency from SharePoint, may take significantly longer. Please note that Square 9 does not control how fast SharePoint or OneDrive can receive or process files. High degrees of latency from SharePoint or OneDrive services can degrade production capture processes in GlobalCapture. This is especially true of the cloudbased SharePoint Online and OneDrive. Performance may be improved by adding additional Core licenses to your GlobalCapture instance. Multiple cores allow simultaneous data exchanges between GlobalCapture and SharePoint or OneDrive. Please contact your Square 9 Softworks reseller for details. Also, note that SharePoint has no mechanism to natively support table-style data structures. While there is no way to pass table or multi-value data directly to SharePoint, this data can still be made available for a SharePoint developer to access as part of a GlobalCapture Workflow process. View GlobalCapture Console From the GlobalCapture console you can view details for the connector, including the Process ID number and timing for SharePoint data operations, which can be helpful when configuring and troubleshooting your Workflow process. 1. To display the console, first ensure that the GlobalCapture instance is stopped in Windows Services. By default, the instance is called GlobalCapture_1. Default GlobalCapture Instance 2. Navigate to the Square9.GlobalCapture.exe file and open it to start the console. By default, the console is located in C:\GetSmart\CaptureServices\GlobalCapture_1\Square9.GlobalCapture.exe. 4 GlobalConnections for SharePoint and OneDrive GlobalConnections for Microsoft SharePoint and OneDrive Guide

11 GlobalCapture Console Configure Workflow To release documents from GlobalCapture to SharePoint or OneDrive, you will need, at minimum, a Workflow with a Call Assembly Node configured to push data to the destination path using the connector DLL file and a Set Process Field Node set to a Process Field with the value of the XML file generated by the configuration utility. Please refer to the GlobalCapture Guide for information on S9 Notation and on creating Workflows and Fields. Create Workflow In the GlobalCapture Designer, create your Workflow, including any extraction and classification needed. Set it to temporarily release locally for testing purposes. Once tested, unpublish it and add the Nodes specific for the release. After completing the connector configuration in the next section, publish the Workflow. When designing your Workflow, make sure that any data that you plan to pass from GlobalCapture to SharePoint fields adheres to the rules enforced by SharePoint for those fields. As SharePoint does not enforce any rules associated with fields in the SharePoint user interface, you will need to make sure that the Workflow is configured correctly. Any errors when posting to SharePoint will result in an errored process in GlobalCapture that will need to be manually corrected by a user or administrator. 1. Create your Workflow. a. Set the Initiator Node to pick up files from the network share and add any other Nodes that you require. b. Temporarily use a Release Node set to release to File to complete the Workflow. c. Run the Workflow to test it and, once successfully tested, unpublish it. Tip: Do Not Create Duplicate Files. You should not intentionally build a release process in a Workflow that will knowingly create repeated instances of duplicate files. This can cause performance issues, as the system needs to continually seek for a unique file before adding it to SharePoint or OneDrive. GlobalConnections for SharePoint and OneDrive GlobalConnections for SharePoint and OneDrive 5

12 2. Edit the Workflow for release to SharePoint or OneDrive. To illustrate this, we will use an example Workflow where documents are imported from the Windows file system, the Process ID number and vendor name are added, a variable is set to define the field mapping and SharePoint connection details, documents are sent to SharePoint, and then the Workflow ends. GlobalCapture Workflow with Basic Capture and Release to SharePoint a. Create a GlobalCapture Field with the Data Type Character to define the path. Called MapPath in this example. b. Add that Field to the Process Field Pane for the Workflow. c. Add a Set Process Field Node for the new Field, set its value to SPXML_<YourMappingFileNameHere> and make note of this filename. Called SPXML_SSPropertyMapper in this example. Set Process Field Node Settings for Release Configuration 6 GlobalConnections for SharePoint and OneDrive GlobalConnections for Microsoft SharePoint and OneDrive Guide

13 d. Replace your temporary Release Node with a Call Assembly Node to connect the Workflow to your configured repository via the connector DLL file. In the Server Path text box, enter your connector assembly path. Enable Merge Documents. C:\GetSmart\CaptureServices\GlobalCapture_1\Square9.O365Connect.dll by default. Call Assembly Node Settings for Release to SharePoint e. Optionally, create a GlobalCapture Field with the Data Type Character to keep track of processes at run time using the Process ID number. Called ProcessID in this example. f. Add that Field to the Process Field Pane for the Workflow. g. Add a Set Process Field Node for the new Field before the Call Assembly Node, set its value to the S9 Notation {PROCESSID}, and make note of its Process Field ID number. In the example, the Field ProcessID was fourth one added to the Pane, therefore 4 is the value used. Set Process Field Node Settings for Process ID Number GlobalConnections for SharePoint and OneDrive GlobalConnections for SharePoint and OneDrive 7

14 While optional, it is useful when troubleshooting to keep track of a specific process using its Process ID number (the identifying number you see in Batch Manager). Be careful when setting this, as passing an invalid number or a mismatch in GlobalCapture and SharePoint field data types will cause an error. Use Process ID Number When Troubleshooting 3. Complete the Connections, but do not publish the Workflow. Tip: Delete Files After Capture. To prevent files from filling up your GlobalCapture working directory: Once in SharePoint or OneDrive you may not need to retain documents locally. Add a Delete Node after the Call Assembly Node to remove them from the working directory. If you do want to keep local copies, after the Call Assembly Node, add a Release Node to release to file or GlobalSearch and then delete them from the working directory. Configure Release Use the configuration utility to configure SharePoint and OneDrive connection details, test the connection, and configure field-mapping details between GlobalCapture and SharePoint or OneDrive. Each release requires specific configuration, resulting in an XML file. 1. To configure the connector, run the Square9.O365Config.exe file. 2. When the Office 365 Release Configuration utility opens, on the Settings tab, in the Settings group: a. Enter the web path to your site in the web URL text box. This is the base endpoint for your site. For SharePoint Server, you can enter either HTTP or HTTPS. For SharePoint Online, you must enter HTTPS. For OneDrive, you must enter the complete URL to your OneDrive Business site, formatted like this example: b. Enter the path of the destination folder in the Target Path text box, using forward slashes. 8 GlobalConnections for SharePoint and OneDrive GlobalConnections for Microsoft SharePoint and OneDrive Guide

15 This can be a nested path. For example, APInvoices/2017 and APInvoices/2017/TelcoVendors are valid destinations. This must always start with Documents for OneDrive. c. Select either SharePoint Online or SharePoint (SharePoint 2013 or SharePoint Server) for your SharePoint type or select OneDrive. 3. You will need to configure the authentication information of the SharePoint or OneDrive user with appropriate permissions to create objects within the SharePoint or OneDrive folders. To do so, in the Credentials group: a. Enter the domain (or machine name if there is no domain) in the Domain text box. This can be left blank if you are using SharePoint Online; data entered here it will be ignored. a. Enter the user account in the Username text box. b. Enter the password in the Password text box. For SharePoint Online, user accounts must be in the form of a valid address. c. To test authentication, click Test. 4. Configure the GlobalCapture Process Fields, in the System group: a. Optionally, enter the ID number of the Field used to identify the Workflow process in the Process Field ID text box. b. To configure a field used for naming a file going into SharePoint or OneDrive, enter its Field ID number in the File Name Field ID text box. GlobalCapture automatically passes a file s original file name as it was on import into the capture process, with the statically set ID number -4. Enter -4 to use the original file name. c. Optionally, to create a SharePoint folder based on a Process Field value, enable Create folder from field. Then enter the Process Field ID number of the Field used for dynamic field creation in the Folder Field ID text box. The value in this Process Field will present in SharePoint s default Name column. The values in the Folder Field ID and File Name Field ID may be assigned by a user in the Validation Station or set by some other Node in the Workflow, like a Classify Node. Configuration Utility 5. To map GlobalCapture to SharePoint fields, on the Field Mapping tab: a. Enter the destination GlobalCapture / SharePoint field name in the SharePoint Name text box. b. Enter the corresponding Process Field ID number in the Square 9 ID text box. GlobalConnections for SharePoint and OneDrive GlobalConnections for SharePoint and OneDrive 9

16 For OneDrive deployments, the Field Mapping tab can be ignored. 6. On the Settings tab, click Save. 7. When prompted for a filename, enter the same SPXML_<YourMappingFileNameHere>.xml filename decided in the Set Process Field Node. The XML configuration file may be manually edited, and copied as necessary. Note that you must use the configuration utility to edit and save password data, since this information is encrypted and only accessible from the utility. SharePoint Mapping 8. In the GlobalCapture Designer, publish the Workflow and run it. 10 GlobalConnections for SharePoint and OneDrive GlobalConnections for Microsoft SharePoint and OneDrive Guide

17 Example: XML File for Mapping Fields. The connector XML file for the example Workflow would look something like the following (although this illustration has some additional Fields). <PropertyMapping> <Config> <WebURL> <DestinationURL>APInvoices</DestinationURL> <Domain>Square9.local</Domain> <FolderCreation>false</FolderCreation> <InstanceType>SharepointOnline</InstanceType> <ProcessIdField>4</ProcessIdField> <FolderField>5</FolderField> <FileNameField>-4</FileNameField> </Config> <Fields> <Field ID="1">Vendor Name</Field> <Field ID="3">Invoice Amount</Field> </Fields> </PropertyMapping> In this example XML file, elements include: WebURL The web path to your site. (SharePoint Online must be HTTPS. OneDrive must be the complete URL to your OneDrive Business site.) DestinationURL The base path where documents will be stored. (For OneDrive, this must always start with Documents. ) Domain The domain (or machine name if no domain) used to authenticate users to SharePoint. Username The user account used to authenticate to SharePoint. Password An encrypted version of the authenticated user s password. FolderCreation The True/False value indicating whether or not a target folder should be dynamically assigned based on a field value. See the FolderField element for more details. InstanceType The type of SharePoint or OneDrive instance you are connecting to. For SharePoint Online, this must be SharepointOnline and for OneDrive, this must be OneDrive. Any other value will default the connection to a local / private version of SharePoint. ProcessIdField A field ID number for the Process ID. If you do not wish to pass the Process ID number, clear the value from the ProcessIdField element. FolderField The Process Field ID number of the field used for dynamic field creation. FileNameField The Process Field ID number of the field used for naming the file in SharePoint. Fields The fields which are mapping between GlobalCapture and SharePoint. ID is the Process Field ID number in GlobalCapture, and Vendor Name and Invoice Amount are the fields in SharePoint, for this example. GlobalConnections for SharePoint and OneDrive GlobalConnections for SharePoint and OneDrive 11

18 Example: Capture and Classify Data. In this GlobalCapture Workflow example, files are captured from the file system, but rather than statically setting data in the Workflow, a Classify Node is used to extract high-value data points. 1. The Initiator Node picks up files from a network share. 2. Unstructured data extraction is used on the documents, pulling an invoice amount based on pattern matching and a vendor phone number based on a data lookup to an external data source. 3. A data lookup is performed on a vendor master data source using the extracted phone number. This allows users to add data to the Vendor Name Field in the process. 4. A Condition Node checks to ensure that the vendor name is present. 5. If no vendor name is found, a user can manually add one in the GlobalCapture Validation Station. 6. If a user rejects the document in Validation, the document is deleted and the process ends. 7. Otherwise, the Process ID number is set. 8. A variable is set to define the field mapping and SharePoint connection details. 9. The document is sent to SharePoint. Example: Capture with Conditional Routing. In this Workflow example, captured documents are classified as purchase orders, invoices, or packing lists for releasing to SharePoint. 1. The Condition Nodes are used to identify the document type. 2. Based on type, the correct mapping / connection information is set for the SharePoint connection. 3. A Set Process Field Node is set to keep track of the Process ID number. 4. The document is sent to one of three locations in SharePoint, based on how it was classified in the Workflow. 12 GlobalConnections for SharePoint and OneDrive GlobalConnections for Microsoft SharePoint and OneDrive Guide