Onboarding Automation

an IBM Cloud Pak® for Business Automation use case

---

Use Case: Content and document services

Use Case Overview: Focus Corp accelerates the use of unstructured content in an employee onboarding use case using teamspaces and secure external file sharing. You will assume the role of Lucy, an HR employee onboarding specialist at Focus Corp. Lucy’s objective is to improve Focus Corp’s process and ensure various onboarding requirements are met in a secure, structured, consistent and timely manner to onboard the new employees. Focus Corp must collaborate both internally and externally during the employee onboarding process as well as enforce structured and adhoc workflows. 

Choose an option:

• Cloud Pak for Business Automation as a Service demo environment (likely an IBMer): your environment is pre-deployed, continue to the Getting Started Lab.
• Install Yourself: To deploy Onboarding Automation on your own environment, continue reading.

Environment

We assume the following products are installed, up and running:

• IBM Cloud Pak® for Business Automation version 22.x
  • Automation Foundation on OpenShift
  • Business Automation Applications (including Studio and App Engine) on OpenShift
  • Business Automation Content Services on VMs or OpenShift
  • Business Automation Navigator on OpenShift
  • Business Automation Workflow (BAW) on VMs or OpenShift Note: only necessary for the last lab step to launch a process from a document

Note:

1. This setup has not been fully tested on non-SaaS environments - there may be slight differences in the setup. For example, specify object CONTENT instead of OS1.
2. It is recommend to clone this GitHub repository rather than individually copying each asset that is required to import into your environment.

Deploy the artifacts

1. Determine your credentials
   1. If using Cloud Pak for Business Automation as a Service (CP4BAaaS):
      1. You will use a single login to access CPE, BAS and BAW
      2. Additionally, create the following from Access Management
         1. Service credientials
            1. Functional ID alias: OA (use something short)
            2. Description: Used by process app Employee Onboarding - Onboard Employee
            3. Note: This service account is used by BAW to launch a process from a document. Additionally, this account is also used to upload sample content using the GraphQL script.
            4. Permissions for this user added below
         2. Users
            1. Add demo users with access to Production environment
               1. Within the Production environment, the user does NOT need any specific roles
         3. Groups
            1. Group: TE_ADMIN
               1. Add only administrative users to this group.
                  1. This access management group identifies users that have access to modify all folders and documents.
                  2. Place the 'OA' service credential into this group
            2. Group: TE_DEMO
               1. Add demo users to this group -OR- add the group ECMoC_Client_CPE_User (Note: 'ECMoC_Client_CPE_User' access mangement group is configured to include 'Participants' (aka 'Production'))
                  1. This access management group identifies users that can:
                     1. Access content (folders/documents)
                     2. Perform redactions on documents
                     3. Launch the Onboard Employee process app
            3. Group: TE_OnboardingAutomation_Redaction
               1. Add the TE_DEMO group to this group
         4. Review the NextGen User Guide for the latest user security required for the Run environment, as of February 2023, it is:
            1. Insights Role: Administrators
            2. Workplace Administrators
            3. Decision Server: Operator
            4. Note: access to the Production environment provides membership into the following access management groups:
               1. Participants
               2. ECMoC_Client_CPE_User (from Particpants)
   2. If deploying on your own OpenShift environment:
      • Make sure you have a login to all required components above
   3. If deploying on your own OpenShift environment based on the demo pattern and running on IBM Red Hat OpenShift on IBM Cloud (ROKS):
      • Install the oc CLI from the Client-side requirements here: V21.0.x. Note: all other Client-side requirements are optional for this install but recommended to manage the ROKS cluster.
2. FileNet Security (Configure in ACCE)
   1. Object Store (default)
      1. ECMoC_Service_Account - Full Control - This object only
      2. ECMoC_Client_CPE_Administrator - Full Control - This object only
      3. ECMoC_Client_ACCE_ClassDesigner - Full Control - This object only
      4. ECMoC_Client_ACCE_ApplicationDesigner - Full Control - This object only
      5. baw_dev_administrators - Full Control - This object only
      6. CPE_Bootstrap_User - Full Control - This object only
      7. ECMoC_Client_CPE_User - Use object store - This object only
   2. Root folder
      1. Administrators - Full Control - This object and all children
      2. ECMoC_Service_Account - Full Control - This object only
      3. TE_ADMIN - Full Control - This object only
      4. TE_DEMO - View properties - This object only
   3. Folder: Focus Corp (Create manually or use the first step from Focus Corp folder structure step below )
      1. Administrators - Full Control - This object and all children
      2. TE_ADMIN - Full Control - This object and all children
      3. TE_DEMO - View properties - This object and all children
   4. Default Instance security
      1. Folder
         1. TE_ADMIN - Full Control - This object only
         2. TE_DEMO - View properties - This object only
         3. #CREATOR-OWNER - Full Control - This object only
      2. Document
         1. Administrators - Full Control - This object only
         2. TE_ADMIN - Full Control - This object only
         3. TE_DEMO - View content - This object only
         4. #CREATOR-OWNER - Full Control - This object only
3. Deploy Content Services
   1. Log into Administration Console for Content Engine (ACCE) and locate your Object Store (generally called OS1 on SaaS and CONTENT on ROKS) and perform the following:
      1. Property Templates - navigate to Data Design, Property Templates and create property templates for:
         1. First Name (String)
         2. Last Name (String)
         3. Application Date (Date Time)
         4. Employee ID (String)
         5. Onboarded (Boolean)
         6. Hire Date (Date Time)
      2. Document sub-class: Employment Application - navigate to Data Design, Classes, Document and create a Document sub-class named Employment Application with these properties:
         1. First Name
         2. Last Name
         3. Application Date
      3. Folder sub-class: Employee - navigate to Data Design, Classes, Folder and create a Folder sub-class called Employee with the following following properties:
         1. First Name
         2. Last Name
         3. Employee ID
         4. Onboarded
         5. Hire Date
   2. Focus Corp folder structure - use either Go scripts or execute using GraphiQL. Note: the Go scripts use GraphQL commands.
      1. Option 1 - Go Script
         1. Install Go
            1. https://go.dev/
         2. Download and review the Go script (located within this GitHub): content-services / graphql / go
            1. Review
               1. Review usage in the HELP file
               2. Review/verify design structure: folders.json
               3. Review/verify data: documents.json
                  1. The content is located in the Focus Corp - Demo Content folder. Create DocumentScript folder and copy the desired content.
               4. Reference info - review GitOps Pattern (IBM Only)
                  1. https://github.ibm.com/dte2-0/ccp-gitops-patterns/blob/main/cp4ba-saas/scripts/main.go
            2. Execute
               1. $go run focusCorpConfig.go -tenant= -env=<dev,run> -action=<design,data> -userpassword=user:password
               2. Execute design (folder.json)
               3. Execute data (documents.json) - ensure content is in subfolder DocumentScript
      2. Option 2 - create directly using GraphiQL
         1. Locate your GraphQL URL, using Cloud Pak for Business Automation as a Service example, the format is:
            1. https://<tenant>.automationcloud.ibm.com/dba/run/content-services-graphql/
         2. Download and review the GitHub script (located within this GitHub): content-services / graphql / FocusCorp-GraphiQL-Design-YYYY_MM_DD-XX.txt
         3. The repository id is OS1 in the script. If your repository id is different, update the script with your repository id
         4. Copy and paste each section and confirm the script executes successfully on your environment
   3. Sample Content - if Option 1 (Go Script), was used in the prior step, this step is no longer necessary as the content was uploaded using the -action=data parameter of the Go script.
      1. Using the Navigator Browse feature, navigate to folder \Focus Corp\Human Resources\Onboarded\Employees\Selena Swift and perform the following:
         1. For Photos - add the images to the Photos subfolder from the GitHub source: content-services / sample-content / Selena Swift / Photos
         2. For Employee Packet - choose one of the methods below:
            1. Using CURL/GraphQL
               1. Review and execute the GitHub script: content-services / graphql / FocusCorp-GraphQL-Data-YYYYY_MMDD-XX.txt
            2. Manual process using Navigator
               1. Download the content from the GitHub source: content-services / sample-content / Selena Swift / Employee Packet and manually upload the following:
                  1. Confidentiality Agreement.pdf (Class: Document)
                  2. Employee Manual.docx (Class: Document)
                  3. Focus Corp - Employment Application.pdf (Class: Employment Application)
                     1. First Name: Selena
                     2. Last Name: Swift
                     3. Application Date: specify any date
         3. TE_DEMO group Author permission to folder: \Focus Corp\Human Resources\Onboarded\Employees\Unsecured
            1. Update the security on the Unsecured folder
               1. TE_DEMO - Modify properties - This object and all children
   4. Navigator Administration
      1. Connections, Repositories - the lab uses two object stores - the FileNet content object store and the BAW target object store
         1. For the FileNet content object store, set the following:
            1. General tab - Display name: Corporate Operations
            2. Configuration Parameters tab:
               1. Workflow connection point - OS1_CP1:1
               2. State icons - enabled for all except Are uploading (requires Aspera plugin)
               3. Task manager connection ID - set using an administrator user ID and password to run background tasks that modify the repository.
               4. Track downloads - set to Enable
               5. Sync services - set to Enable
               6. Document History - set to Enable
               7. Teamspace management - set to Enable
                  1. Enable owners to delete teamspace, included contents - checked
               8. Role-based redactions - set to Enable
               9. Entry template management - set to Enable
            3. Set Browse configuration, Selected Properties for:
               1. Show in Details View: Name, Content Size, Last Modifier, Date Last Modified, Major Version Number, Description
               2. Show in Magazine View: Name, Last Modifier, Date Last Modified, Likes, Tags, Downloads, Comments
               3. Note: if you are unable to specify the fields above, you may need to recreate your repository.
         2. For the BAW target object store, ensure that the repository configuration setting for General, Display Name is set to Workflow Operations
      2. Menus
         1. Copy the Default document context menu menu option and add options for Launch Process and Share (Share is only needed for Additional Assets section)
            1. Update your desktop and update Context Menus - Content Context Menus - Document context menu to the new menu
         2. Copy the Default teamspace content list context menu menu option and add options for Launch Process and Share
            1. Update your desktop and update Context Menus - Content Context Menus - Teamspace content list context menu to the new menu
      3. Viewer Maps - ensure that the first two viewers are set for:
         1. Repository Type=FileNet Content Manager, Viewer=Video Viewer, File Type=video/mp4, video/x-m4v, video/webm, video/quicktime, audio/mpeg, audio/mp4, audio/x-m4a, audio/x-m4b (select all the video/audio formats)
         2. Repository Type=FileNet Content Manager, Viewer=Daeja ViewONE Virtual, File Type=All file types
         3. Update your desktop and update Viewer map setting to use this viewer map
      4. Desktops - edit your default desktop with the following settings:
         1. General tab
            1. Desktop Configuration section
               1. Merge and Split - set to Enable
               2. Sync services - set to Enable
               3. Edit Service - set to Enable
               4. Office for the web service - set to Enable and Allow collaborative editing
               5. Email settings - Use the HTML-based email service checkbox enabled along with Allow users to send attachments
               6. Additional settings
                  1. Show security settings during add and check in actions - checkbox disabled
                  2. Enable this desktop for FileNet P8 workflow email notification - checkbox enabled
                  3. When using the Open and Preview actions, display documents in the current window - checkbox enabled
               7. Document History - set to Enable
         2. Repositories tab - selected repositories: Workflow Operations, Corporate Operations, and optionally FPOS for Records Management
         3. Layout tab
            1. Displayed features - Home, Browse, Search, Share, Teamspaces, Entry Template Manager, Work, Work Dashboard, Cases, Reports
            2. Default feature - Home
            3. Additional Desktop Components
               1. Document thumbnails: set option to Show
               2. Status bar: set option to Show
               3. Content list checkboxes: set option to Show
      5. Role Based Redaction
         1. From Navigator Administration, click Role-based Redactions and set up the following:
            1. Reasons - create/validate that the following reasons exists:
               1. Credit Card Number (should already be created)
               2. Social Security Number (should already be created)
               3. Name: PII
                  Description: Personally Identifiable Information
            2. Policies and Roles
               1. Click Policies and Roles
               2. If not connected, connect to your repository: Corporate Operations
               3. Redaction Roles - click New Redaction Role
                  1. TE Redaction Editor
                     1. Name: TE Redaction Editor
                     2. Type: Editor
                     3. Description: TE Redaction Editor
                     4. Membership: click New Editors
                        1. Add group: TE_OnboardingAutomation_Redaction
                  2. TE Redaction Viewer
                     1. Name: TE Redaction Viewer
                     2. Type: Viewer
                     3. Description: TE Redaction Viewer
                     4. Membership: Editors
                        1. Add existing editor: TE_OnboardingAutomation_Redaction
               4. Redaction Policy - click New Redaction Policy
                  1. Name: TE Redaction Policy
                  2. Description: TE Redaction Policy
                  3. Redaction Reasons: Credit Card Number, Social Security Number, PII
                  4. Redaction editors: TE Redaction Editor
                  5. Redaction viewers: TE Redaction Viewer
   5. Navigator features
      1. Search
         1. Create any type search (ie. Class=Employment Application) with following properties:
            1. Name - Employment Application Search
            2. Description - Employment Application Search
            3. Save in - Corporate Operations / Focus Corp / X Configuration
            4. Class - Employment Application
            5. Share search with - Everyone in my company
      2. Teamspaces
         1. Create Employee Onboarding teamspace template as documented in the Getting Started Lab, section 4.1.1 Teamspace Template Builder.
            1. Template name: Employee Onboarding
            2. Template description: Teamspace Template for Employee Onboarding
            3. Share template with**: Everyone in my company
4. Deploy BAW artifacts
   1. From the Development environment, select Build, Studio (Business Automation Studio) and navigate to Business automations
   2. Import Employee_Onboarding - OnboardingAutomation-YYYY.MM.DD_##.twx
   3. Open the Onboarding Automation process app and navigate to Process App Settings -> Servers
      1. Edit the settings for hostname, port, context path, repository, user id, password and so forth for your Enterprise Content Management Server
         1. Example values: <tenant>.automationcloud.ibm.com, 443, /dba/dev/openfncmis_wlp/services11, OS1, <service id>, <service id password>
         2. Example values: fncm-dev-<tenant>.blueworkscloud.com, 443, /openfncmis_wlp/services11, OS1, <service id>, <service id password>
      2. Use the Test connection button to validate connectivity
   4. Confirm settings for process: Onboard Employee - Start
      1. General - Event Properties: Type should be set to Employment Application
      2. Validate/Edit Data Mapping
         1. Application Date => tw.local.employeeApplicationDate
         2. First Name => tw.local.employeeFirstName
         3. Last Name => tw.local.employeeLastName
         4. Name => tw.local.Name
         5. ID => tw.local.ecmDocID
   5. Save changes and optionally confirm the process app is installed correctly.
      1. To confirm the process app is installed correctly, create a document with class Employment Application and then right-click on the document to select the Workflow, Launch Process menu option.
         1. From the Launch Process dialog, select Onboard Employee and confirm the Launch UI dialog is displayed.
   6. From Studio (Business Automation Studio), create a new snapshot of the workflow application. Name the snapshot something very shot such as V2. Naming it V2 will allow the launching of the process to be displayed as:
      1. Name: V2
      2. Description: Automation Onboarding
   7. Install the new snapshot to your Run ProcessServer
   8. From the Production environment, access Process Admin Console and go to Installed Apps
      1. Select the Employee Onboarding process app
      2. Select Team Bindings
         1. Select the group TE_DEMO as a member for all the teams (All Users, Managers, Managers of All Users, Process Owner)
      3. Select Servers
         1. Select CONTENT_SERVICES_SERVER and then update the Context Path to the Run environment (ie. /dba/run/openfncmis_wlp/services11)
         2. Use the Test Connection button to test the connection.
         3. Click the Apply button to save the configuration
5. Deploy Business Automation Studio artifacts
   1. From the Development environment, select Build, Studio
   2. From Business applications, import the Onboarding Automation application using Onboarding_Automation - App - YYYY.MM.DD_XX.twx
   3. No edit of the application should be required but if an edit is done, create a new snapshot
   4. Export the application - select Export this version to be published (.zip)
6. Deploy Business Automation Navigator artifacts
   1. Login to Business Automation Navigator's admin desktop
      1. If using Cloud Pak for Business Automation as a Service: Production -> Manage solutions -> Publish -> Business Automation Navigator
      2. If deploying on your own OpenShift environment: use your Navigator URL with ?desktop=appDesktop1 added to the end and use the menu to go to Administration
   2. Select Connections on the left, edit the Application Engine Connection (generally called APPENGO) and then select Connect
      1. Click the Applications tab
      2. If using Cloud Pak for Business Automation as a Service: import the application ZIP file
      3. If deploying on your own OpenShift environment: import the application ZIP file
   3. Edit Details from the application's menu and add appropriate teams to the Permissions table, such as #AUTHENTICATED-USERS to make the app available to everyone
   4. Edit the desktop of your choice (generally appDesktop1) and on the Layout tab, select the application
   5. To verify, confirm that the Onboarding Automation application is displayed in Business Automation Apps

Contributors

• Lead content developer Thomas Yang