GWE Documentation

Workplace Integration Guide

Since v2024.04.4.0 GWE allows you to create and manage workflow requests directly from Workplace.
The integration between GWE and Workplace requires a few manual steps which we will go through in detail below.

ℹ️

Note: If you have not made any modifications to the OOB Workplace source code in your project you can just copy, paste & replace all files from the schema/ab-products/essential directory of the kit into the schema/ab-products/essential directory of your project.

Prerequisites

This operation will require you to run 2 build commands: one for Workplace itself and one for GWE.
For this you will need two things:

NodeJs

The NodeJs version may differ depending on your ARCHIBUS version.
e.g. ARCHIBUS v2024.04.01.115 requires NodeJs v20.13.1

To know which version of node you need, head over to schema/ab-products/essential/dev/workplace/package.json, open the file and look for the engines property at the very end.
e.g.

package.json

"engines": {
  "node": "20.13.1"
}

ℹ️

Tip: The easiest way to use one or more NodeJs versions is to do it via the node version manager for Mac/Linux also known as nvm.
For Windows there is Corey Butler’s nvm-windows which serves the same purpose.

Yarn

By default, NodeJs comes packed with npm (node package manager) to install dependencies for your projects.
However we will use a different package manager for our build process: yarn because npm is slower, not as good at figuring out mismatching dependency versions and it’s what ARCHIBUS uses to build the Workplace app.

With NodeJs installed, open a terminal and install it with the following command:

npm install --global yarn

If everything went well you should be able to see the yarn version when you write:

yarn --version

Installing the integration

With the prerequisites installed, we can go ahead and rebuild the Workplace sources with the GWE modifications.

Copy the new files

Inside the unarchived GWE kit you will find the following files and directories that need to be copied at their corresponding locations in your ARCHIBUS project directory.

- - - - baseGWE.config.js
        devGWE.config.js
        prodGWE.config.js

Note: The schema\ab-products\essential\dev\workplace\gwe directory needs to be copied in its entirety.

Patch OOB files

Certain OOB files need to be modified in order to display GWE’s Create / Management views.
We’ll begin with the package.json file that needs to incude the GWE build scripts.
Copy and paste the highlighted lines in the OOB files.

schema/ab-products/essential/dev/workplace/package.json

"scripts": {
  "test": "jest",
  "webpack": "webpack",
  "develop": "npm run webpack -- --mode development --config webpack/dev.config.js --env PLATFORM=local --env VERSION=stag",
  "production": "npm run webpack -- --mode production --config webpack/prod.config.js --env PLATFORM=local --env VERSION=stag --env patch",
  "watch": "npm run webpack -- --watch --config webpack/dev.config.js --env PLATFORM=local --env VERSION=stag",
  "extractlocalizedstrings": "node scripts/extract-localized-strings.js",
  "format": "npm run prettier -- --write",
  "prettier": "prettier \"**/*.+(js|jsx|css)\"",
  "lint": "eslint src",
  "validate": "npm run lint && npm run prettier -- --list-different",
  "storybook": "start-storybook -s ./src/assets/img -p 9001 -c .storybook",
  "build": "npm run production && npm run extractlocalizedstrings",
  "scriptsComment": "echo 'scripts -> `test`, `webpack` and `storybook` are not in use currently.'",
  "prepare": "cd ../../../../.. && husky schema/ab-products/essential/dev/workplace/.husky",
 
  "lintGWE": "eslint --ext .js,.jsx,.css ./gwe",
  "developGWE": "webpack --mode development --config webpack/devGWE.config.js --env PLATFORM=local --env VERSION=stag",
  "watchGWE": "webpack --watch --config webpack/devGWE.config.js --env PLATFORM=local --env VERSION=stag",
  "productionGWE": "npm run webpack -- --mode production --config webpack/prodGWE.config.js --env PLATFORM=local --env VERSION=stag --env patch",
  "buildGWE": "npm run productionGWE && npm run extractlocalizedstrings"
},

schema/ab-products/essential/dev/workplace/src/lazyLoad.js

const ServiceRequestDetailPage = lazy(() =>
  import('./pages/ServiceRequestDetail/ServiceRequestDetailPage')
)
 
// (Asc)
const WfManageViewTabs = lazy(() =>
  import('./pages/WfManageView/WfManageViewTabs')
)

schema/ab-products/essential/dev/workplace/src/constants/sharedconstants.js

export const MEETINGS_MORE_LIST = 'MEETINGS_MORE_LIST'
export const WORKSPACE_MORE_LIST = 'WORKSPACE_MORE_LIST'
export const SERVICE_MORE_LIST = 'SERVICE_MORE_LIST'
 
// (Asc)
export const GWE_MANAGE_VIEW = 'GWE_MANAGE_VIEW'
 
export const MEETING_SCHEDULE = 'MEETING_SCHEDULE'
export const MEETING_CREATE = 'MEETING_CREATE'

schema/ab-products/essential/dev/workplace/src/containers/Dashboard/Dashboard.js

    // ... OOB code
 
    import {_L, useLocaleState} from '../../context/LocaleContext'
    import {getTempDocumentUrl} from '../../api/archibus/DocumentApi'
    import * as GWE from '../../../gwe/utils/data'
    import {useViewFetch} from '../../utils/fetch'
    import {setHtmlTitle} from '../../utils/accessibility'
 
    // ... OOB code
 
    import {
      DASHBOARD,
      KIOSK_CONTAINER,
      LOGON_CONTAINER,
      MEETING_SPACE,
      MOVE,
      NO_SERVICE,
      SERVICE_CATALOG,
      SERVICE_SEQUENCE,
      WAY_FINDER,
      WORKSPACE,
      GWE_MANAGE_VIEW
    } from '../../constants/sharedconstants'
 
    // ... OOB code
 
      const {data: building} = useViewFetch({
        api: fetchBuilding,
        parameters: {blId: activeFloor.blId},
        initialState: {},
        onChangeOf: [activeFloor]
      })
 
      // (Asc)
      const {data: gweViews} = useViewFetch({
        api: GWE.getManageViews,
        parameters: {},
        initialState: [],
        onChangeOf: []
      })
 
      setHtmlTitle(getApplicationTitle(_L, localeState))
    
    // ... OOB code
 
  const onDashboardCardClick = content => {
    let action = content.action
    // Link to the service catalog
    action = action === SERVICE_SEQUENCE ? SERVICE_CATALOG : action
    // Display Find Person, Room or Equipment screen
    action = action === WAY_FINDER ? KIOSK_CONTAINER : action
 
    trackUsage(
      'Workplace',
      configState,
      user,
      buildTrackUsageProperties(
        content.viewTitleForUsageAnalytics,
        content.titleForUsageAnalytics,
        content.fileNameForUsageAnalytics
      )
    )
 
    uiDispatch({
      type: 'setContent',
      payload: {
        content: action,
        parentPage: DASHBOARD,
        props: {
          building,
          wfData: content.wfData // (Asc)
        }
      }
    })
  }
 
// ... OOB Code
 
  // (Asc)
  const getGweCardsContent = () => {
    const gweCards = gweViews.map(view => ({
      imgUrl: getTempDocumentUrl(
        'wf_mng_view',
        {mng_id: view.mngId},
        'wpl_img'
      ),
      title: view.description,
      contentText:
        view.wplDescription ||
        _L({
          key: 'This description should be added in the future.',
          localeState
        }),
      buttonText: _L({
        key: 'View',
        localeState
      }),
      action: GWE_MANAGE_VIEW,
      wfData: {...view}
    }))
 
    return gweCards
  }
 
  const getDashboardServicesRow = () => {
    const dashboardCardsAction = []
    if (search) {
      dashboardCardsAction.push(getDashboardCardContent(WAY_FINDER))
    }
    if (workingspace) {
      dashboardCardsAction.push(getDashboardCardContent(WORKSPACE))
    }
    if (meetingspace) {
      dashboardCardsAction.push(getDashboardCardContent(MEETING_SPACE))
    }
    if (createrequest) {
      dashboardCardsAction.push(getDashboardCardContent(SERVICE_SEQUENCE))
    }
 
    // Add the GWE cards (Asc)
    getGweCardsContent().forEach(cardContent => {
      dashboardCardsAction.push(cardContent)
    })
 
// ... OOB Code
 
const LeftPanel = styled.div`
  width: 100%;
  height: 100%;
  box-sizing: border-box;
  grid-row: 1;
  grid-column: 1;
  display: flex;
  flex-direction: column;
  ${props =>
    props.isSingleService
      ? ''
      : 'padding: 100px; overflow-y: auto; '} @media(max-width: 1039 px) {
    grid-column: 1 / 3;
  }
`

schema/ab-products/essential/dev/workplace/src/containers/Dashboard/DashboardCard.js

import React, {useState, useEffect} from 'react'
import styled from 'styled-components'
import {useConfigState} from '../../context/ConfigContext'
import {_L, useLocaleState} from '../../context/LocaleContext'
import Tooltip from '../../evo/components/Tooltip/Tooltip'
import Icons from '../../components/Icons'
import {
  MEETING_SPACE,
  SERVICE_SEQUENCE,
  WAY_FINDER,
  WORKSPACE,
  GWE_MANAGE_VIEW
} from '../../constants/sharedconstants'
import {parseTokens, typography} from '@runeffective/evo-core'
import {keyDown} from '../../utils/accessibility'
import gweLogo from '../../../gwe/assets/gwe-logo.png'
 
const DashboardCard = ({content, action, click}) => {
  const configState = useConfigState()
  const localeState = useLocaleState()
  const {theme} = configState
 
  const {title, imgUrl, contentText} = content
 
  // (Asc)
  const [imgData, setImgData] = useState(imgUrl)
  useEffect(() => {
    if (imgData instanceof Promise) {
      imgData.then(fetchedData => setImgData(fetchedData))
    }
  }, [])
 
  const getIcon = () => {
    switch (action) {
      case WAY_FINDER:
        return (
          <Icons
            id={'way_finder'}
            color={theme.contentOnSurface}
            icon={'WAY_FINDER_ARROW'}
          />
        )
      case WORKSPACE:
        return (
          <Icons
            id={'workspaces'}
            color={theme.contentOnSurface}
            icon={'WORKSPACE_ICON'}
          />
        )
      case MEETING_SPACE:
        return (
          <Icons
            id={'meeting_spaces'}
            color={theme.contentOnSurface}
            icon={'MEETING_ICON'}
          />
        )
      case SERVICE_SEQUENCE:
        return (
          <Icons
            id={'services'}
            color={theme.contentOnSurface}
            icon={'SERVICE_REQUESTS'}
          />
        )
      // (Asc)
      case GWE_MANAGE_VIEW:
        return (
          <Tooltip text={_L({key: 'Manage view', localeState})}>
            <img width={30} height={30} src={gweLogo} />
          </Tooltip>
        )
      default:
        return null
    }
  }
 
  const titleId = `${action.toLowerCase()}_dashboard_card_title`
  const contentId = `${action.toLowerCase()}_dashboard_card_content`
 
  const onClick = () => {
    click && click(content)
  }
 
  return (
    <CardContainer
      bgColor={theme.white}
      boxShadow={theme.shadowCard}
      aria-labelledby={titleId}
      aria-describedby={contentId}
      onClick={onClick}
      onKeyDown={e => keyDown(e, onClick)}
    >
      <ImageContainer>
        <Image alt="" src={imgData} />
      </ImageContainer>
      <BottomContainer>
        <Content>
          <TitleContainer>
            <IconContainer>{getIcon()}</IconContainer>
            <Title id={titleId} textColor={theme.contentOnBackground}>
              {title}
            </Title>
          </TitleContainer>
 
          <ContentText id={contentId}>{contentText}</ContentText>
        </Content>
      </BottomContainer>
    </CardContainer>
  )
}

schema/ab-products/essential/dev/workplace/src/router/utils/mainPagesComponentDefinition.js

import {
  BookingLocate,
  BookingsCalendarPage,
  BuildingListPage,
  ConferenceRoom,
  EmployeeSearch,
  EquipmentQR,
  KioskContainer,
  MeetingBooking,
  MeetingList,
  MeetingSpaceShowMeeting,
  MeetingSpacesSequence,
  Move,
  MoveSequence,
  RegisterKiosk,
  RoomQR,
  ServiceCatalog,
  ServiceRequest,
  ServiceRequestDetail,
  ServiceRequestDetailPage,
  ServiceRequestList,
  Workspace,
  WorkspaceBooking,
  WorkspaceList,
  WorkspaceMoreList,
  WorkspacesEdit,
  WfManageViewTabs // (Asc)
} from '../../lazyLoad'
 
// ... OOB code
 
    case Constants.SERVICE_REQUEST_DETAIL_PAGE: {
      const activityLogId =
        properties &&
        properties.contentProps &&
        properties.contentProps.activityLogId
          ? properties.contentProps.activityLogId
          : ''
      component = <ServiceRequestDetailPage activityLogId={activityLogId} />
      break
    }
 
    // (Asc)
    case Constants.GWE_MANAGE_VIEW: {
      component = (
        <WfManageViewTabs
          wfData={properties.contentProps?.wfData ?? {}}
          parentPage={properties.parentPage}
        />
      )
      break
    }
  }

schema/ab-products/essential/dev/workplace/src/utils/servicerequests.js

import {
  REJECTED,
  CANCELLED,
  COMPLETED,
  COMPLETED_V,
  CLOSED
} from '../constants/sharedconstants'
import {isEmpty} from '.'
 
// (Asc)
export const fetchWfRequests = ({
  numberOfRecords = 1000,
  wfTypes = '',
  searchValue = ''
}) => {
  const parameters = []
  parameters.push({
    name: 'wfTypes',
    value: wfTypes.map(wfType => `'${wfType}'`).join(', ')
  })
  parameters.push({
    name: 'applyWfTypesRestriction',
    value: true
  })
 
  if (searchValue && !isEmpty(searchValue.trim())) {
    parameters.push({
      name: 'applySearch',
      value: true
    })
    parameters.push({
      name: 'searchString',
      value: searchValue.trim()
    })
  }
 
  return Data.getPagedDataFromDataSource(
    'ab-selfservice-dashboard.axvw',
    'wfRequests',
    null,
    parameters,
    1,
    numberOfRecords
  ).catch(err => {
    console.log(
      'ERROR in ab-selfservice-dashboard.axvw "wfRequests" datasource: ' + err
    )
    return Promise.resolve({data: [], total: 0})
  })
}

Add the following datasource anywhere inside ab-selfservice-dashboard.axvw:

schema/ab-products/essential/views/selfservice/ab-selfservice-dashboard.axvw

<!-- ASC-RO -->
<dataSource id="wfRequests" usePreparedStatement="true">
    <table name="wf_requests" role="main"/>
    <field table="wf_requests" name="bl_id"/>
    <field table="wf_requests" name="block_id"/>
    <field table="wf_requests" name="color"/>
    <field table="wf_requests" name="request_id"/>
    <field table="wf_requests" name="requestor"/>
    <field table="wf_requests" name="description"/>
    <field table="wf_requests" name="date_requested"/>
    <field table="wf_requests" name="date_end"/>
    <field table="wf_requests" name="status"/>
    <field table="wf_requests" name="time_requested"/>
    <field table="wf_requests" name="wf_type"/>
 
    <restriction type="sql"
                 sql="(${sql.dateDiffInterval('month', 'wf_requests.date_requested', sql.currentDate)} &lt;= 6) AND ${sql.getRestriction('wfTypesRestriction', '1=1')} AND ${sql.getRestriction('actionsRestriction', '1=1')} AND ${sql.getRestriction('search','1=1')}"/>
 
    <parameter name="searchString" dataType="text" value="%"/>
    <parameter name="applySearch" dataType="boolean" value="false"/>
    <parameter name="applyWfTypesRestriction" dataType="boolean" value="false"/>
    <parameter name="wfTypes" dataType="text" value = "" array="true"/>
 
    <restriction id="search" enabled="applySearch" type="sql" sql="(
      UPPER(wf_requests.bl_id) LIKE ('%' ${sql.concat} UPPER(${sql.getBindVariable('searchString')}) ${sql.concat} '%')
        OR UPPER(wf_requests.block_id) LIKE ('%' ${sql.concat} UPPER(${sql.getBindVariable('searchString')}) ${sql.concat} '%')
        OR UPPER(wf_requests.color) LIKE ('%' ${sql.concat} UPPER(${sql.getBindVariable('searchString')}) ${sql.concat} '%')
        OR UPPER(wf_requests.request_id) LIKE ('%' ${sql.concat} UPPER(${sql.getBindVariable('searchString')}) ${sql.concat} '%')
        OR UPPER(wf_requests.requestor) LIKE ('%' ${sql.concat} UPPER(${sql.getBindVariable('searchString')}) ${sql.concat} '%')
        OR UPPER(wf_requests.description) LIKE ('%' ${sql.concat} UPPER(${sql.getBindVariable('searchString')}) ${sql.concat} '%')
        OR UPPER(wf_requests.date_requested) LIKE ('%' ${sql.concat} UPPER(${sql.getBindVariable('searchString')}) ${sql.concat} '%')
        OR UPPER(wf_requests.date_end) LIKE ('%' ${sql.concat} UPPER(${sql.getBindVariable('searchString')}) ${sql.concat} '%')
        OR UPPER(wf_requests.status) LIKE ('%' ${sql.concat} UPPER(${sql.getBindVariable('searchString')}) ${sql.concat} '%')
        OR UPPER(wf_requests.time_requested) LIKE ('%' ${sql.concat} UPPER(${sql.getBindVariable('searchString')}) ${sql.concat} '%')
        OR UPPER(wf_requests.wf_type) LIKE ('%' ${sql.concat} UPPER(${sql.getBindVariable('searchString')}) ${sql.concat} '%')
      )"/>
    <restriction id="wfTypesRestriction" type="sql" enabled="applyWfTypesRestriction"
                 sql="wf_requests.wf_type IN (${sql.getBindVariable('wfTypes')})"/>
    <restriction id="actionsRestriction" type="sql" sql="EXISTS (SELECT 1 FROM wf_action_log WHERE wf_requests.request_id = wf_action_log.pkey_value AND wf_action_log.wf_type = wf_requests.wf_type AND user_name=${sql.literal(user.name)})"/>
 
    <sortField table="wf_requests" name="request_id" ascending="false"/>
</dataSource>

Build Workplace

Open up a terminal in schema/ab-products/essential/dev/workplace and run the following command:

yarn build

Wait for the process to finish.
After that it’s time to build the GWE app:

yarn buildGWE

With this last step you have finished building the integration.

Using the integration

Now that the integration is installed you can test it by setting the Use in Workplace field to true when defining / editing a management view.

Smart Services / Workflow Engine / Define Management Views

To try it out, create a new management view or select an existing one and switch the Use in Workplace to Yes.
Two additional fields will appear: Workplace Image and Workplace Description.

Workplace Configuration

💡

Caveat 1: The image must have an aspect ratio of 3:2 to match the OOB ones.

💡

Caveat 2: Updating an image will have no effect if the updated image has the same file name as the previous one. This is due to the fact that Workplace caches its images inside \schema\ab-products\essential\workplace\tmp\images. If you want to see the changes, you must manually delete the cached image from the directory.

With the field set to Yes just click on Design to save the form values and then you can open the Workplace application. You should see your bucket alongside the OOB ones.

Clicking on it will open a view with two tabs: Create and Manage.

You can also create requests by switching to the Create tab.

How to Install Roles