Configuration guide for the Asset App integration

• 1. Prerequisites
  • 1.1 Functional prerequisites
  • 1.2 Access and credentials
  • 1.3 Integration Platform setup (Spacewell consultants only)
• 2. Asset app configuration
  • 2.1 Add users
  • 2.2 [Optional] Custom logo on form
  • 2.3 Configure notification webhook
• 3. Asset configuration
  • 3.1 Module activation
  • 3.2 Configure mappings in External App
  • 3.3 Reveal secret key
  • 3.4 Additional configuration
  • 3.5 Link system users to the External App
• 4. Integration Platform configuration
  • 4.1 Create Asset app connector
  • 4.2 Create Asset connector
  • 4.3 Create flows
    • 4.3.1 Asset to Asset app
    • 4.3.2 Asset app to Asset
• 5. How to get started
• 6. Additional information, options, and user guides

This page describes the steps to set up the Asset app integration on the Asset app, Asset and Integration Platform side.

This document is for Spacewell consultants.

1. Prerequisites

Before setting up the Asset app integration, ensure the following prerequisites are met:

1.1 Functional prerequisites

• The Corrective Work Orders module and/or Preventive Maintenance Work Orders module must be activated in Asset.

1.2 Access and credentials

• Valid login credentials for the Asset app customer account

  • These must be requested via email from and provided by the Asset Product Team.

1.3 Integration Platform setup (Spacewell consultants only)

⚠️ This section is only relevant for Spacewell consultants.
For partners, the steps below are handled by Spacewell.

The Asset app communicates with Asset via the Integration Platform. Therefore, the following setup is required:

• An Integration Platform tenant must exist

  • If the tenant does not yet exist, request its creation via the Asset Product Team (email)

• Client credentials for the Integration Platform tenant

  • Client ID

  • Client Secret
    For a new tenant, these will be provided when the tenant is created.
• Integration Platform login credentials (for configuration purposes)

  • Required for Spacewell consultants to configure the integration

    For a new tenant, these will be provided when the tenant is created.

So, when requesting a new Asset App tenant via email to the Asset Product Team, include a request to create an Integration Platform tenant if one does not yet exist.

2. Asset app configuration

2.1 Add users

Go to https://assetapp.spacewell.com/ and use the login credentials provided by the Product team for the specific customer.

Go to Account → Users:

Add the users who are going to handle work orders via the Asset app. Assign the role 'Company User (Mobile Only)' to the added users.

Make sure the user's email address matches the email address of the corresponding user in Asset added to the Asset App external app (see below for these steps).

More information on the available roles, can be found via the Asset app (GoCanvas) Help Center: https://help.gocanvas.com/hc/en-us/articles/26312342524823-The-Seven-User-Roles

Assign the new user directly to the available forms by selecting them:

Info

When a new user is created, the administrator can decide to let the user enter a password, or the password can already be pre-defined by the administrator. In both cases the specified email address will receive an email.

Email (password pre-defined by the administrator):

Email (password to be determined by user):

2.2 [Optional] Custom logo on form

Go to Forms:

By default, the Dutch, English, German, or French (the consultant informed the Product team, which language is desired) default work order form is made available for the new Asset app account and will have the Spacewell logo.

Click on the gear icon to open the settings of the specific form.

Change the icon to a customer-specific icon. This icon is used when a PDF is generated, when a user submits a work order.

2.3 Configure notification webhook

To make sure that Asset app also triggers a notification to Asset once a dispatch on a Form has been completed, an integration URL needs to be configured on each form. The integration URL contains the tenant name, which is set up in the Integration Platform (chapter 4.1 Create tenant).

To show the integration options, go to Forms → Edit:

Add /show_integration_options in the URL and press Enter:

https://assetapp.spacewell.com/forms/5702497 -> https://assetapp.spacewell.com/forms/5702497/show_integration_options

 The integration options screen becomes visible. Click on 'Activate Submission Creation Webhook.':

Enter the following URL in the URL field: (make sure to not forget the tenant name at the end of the URL):

• The ‘Format’ must be changed from ‘JSON’ to 'XML (Deprecated)
• The Tag must be left empty

Click Save to confirm the configuration.

3. Asset configuration

3.1 Module activation

Activate the Asset app integration via the module activation: Asset app integration module activation and information

3.2 Configure mappings in External App

Go to Module settings → Integrations tab (only visible if multiple integrations are activated, otherwise the Asset app tab will directly show) → Asset app tab → Asset app external apps include:

Select the Asset app External app and navigate to the Mappings include:

All the applicable mappings are automatically added to the external app by the module activation. Make sure all mappings are configured based on the list below. Some values are automatically filled in and some values need to be manually configured:

• base_url: this value is automatically filled in → 'integration.spacewell.com'
• client_id: enter the value 'Client ID' that has been provided via email
• client_secret: enter the value 'Client Secret' that has been provided via email
• default_form*: the default form id needs to be provided, to ensure that the work order from Axxerion is created in Asset app backend for the correct form. The default form id (either the Dutch, English, German or French) form can be obtained by opening the form in Asset app backend and copying the id from the last part of the URL (https://assetapp.spacewell.com/forms/5567321)
• grant_type: this value is automatically filled in → 'client_credentials'
• tenant_id: enter the tenant name that has been provided via email
• token_url: this value is automatically filled in → 'https://integration.spacewell.com/api/v2/oauth/urlencoded/token'
• webhook: this value is automatically filled in, but needs to be supplemented by the Asset client reference → 'https://integration.spacewell.com/api/v2/push/axxerion/<client reference>'

3.3 Reveal secret key

Go to Module settings → Integrations tab (only visible if multiple integrations are activated) → Asset app tab → Asset app external apps include.

Select the Asset app External app, make sure the ‘Commission' is set to ‘active’ and select the Trust relation include and click on the 'Key' hyperlink:

Click on 'Reveal key' if there is already a secret key generated.

Click on 'Generate key' if there is no secret key yet.

Copy the secret key and write it done. This secret key will be needed in the Asset connector configuration later in this guide.

3.4 Additional configuration

Make sure the following configuration has been completed in Asset:

• Requests module activated and configured
• Corrective- and/or preventive maintenance work orders module activated and configured
• User profiles have been created for the service desk employee and the internal contractors
• Users have been created and the correct user profile has been assigned

3.5 Link system users to the External App

All users in Asset who are going to use the Asset app to handle corrective- and/or preventive maintenance work orders need to be linked to the external app.

Go to Module settings → Integrations tab (only visible if multiple integrations are activated) → Asset app tab → Asset app external apps include.

Select the Asset app External app and navigate to the System user include:

Click on Search to show the already linked system users.

Click on Assign to link new system users:

Search and select all applicable users and click Ok to link them to the external app:

4. Integration Platform configuration

The Integration Platform allows the synchronization of the data between the external app and Asset. You can configure the flows between the app and Asset within the Integration Platform.

Log in to the Integration platform with the provided credentials via https://integration.spacewell.com/

4.1 Create Asset app connector

Select the applicable tenant from the drop-down menu in the top right corner.

Go to Asset App Sync > Connectors. In Actions, select “Add” to create a new connector:

Select type GOCANVAS and enter following information:

Click Add to confirm.

4.2 Create Asset connector

In Reservation Sync > Connectors > Actions, select “Add” to create a new connector.

Select type AXXERION and enter following information:

Click Add to confirm.

4.3 Create flows

4.3.1 Asset to Asset app

1. Go to Asset App Sync > Flows. In Actions, select “Add” to create a new flow:

2. Enter the name of the flow (use: ‘Asset to Asset App’) and select Flow type 'Axxerion work order to Gocanvas':

3. Add to confirm the new flow.
4. Upon mouse over, select … > Edit on the Asset to Asset app flow:

5. Select the Mappings tab and go to Manage mappings:

6. Select Add mapping to map the Asset fields to the Asset app form fields

7. Add all applicable mappings that are available in the default form:

8. Select Confirm and Save.

4.3.2 Asset app to Asset

Similar to the steps above, where flow “Asset to Asset app” was defined:

1. Go to Asset App Sync > Flows. In Actions, select “Add” to create a new flow.
2. Enter the name of the flow (use: ‘Asset App to Asset’) and select Flow type 'Gocanvas to Axxerion Workorder'.
3. Add to confirm the new flow.
4. Upon mouse over, select … > Edit on the Asset to Asset app flow.
5. Select the Mappings tab and go to Manage mappings.
6. Select Add mapping to map the Asset fields to the Asset app form fields.
7. The following mapping is applicable in the default form in Asset app:

8. Click to Confirm.
9. Still in Mappings tab, select Transition rules:

10. Add rule to add the following transaction rules:

• Work has to be rescheduled has valuetype Empty then change the destination to End work
• Work has to be rescheduled has valuetype Not empty then change the destination to Reschedule

Or, depending on the default work order form language in the Asset App backend, in another language (e.g. in Dutch: ‘Werk moet opnieuw worden gepland' or in German “die Arbeiten müssen neu geplant werden“).

11. Click to Save to save the transition rules, and click on Save again to save the flow.

5. How to get started

Once all the steps above are completed, the integration is live, and the Asset App can be used to handle work orders.

Make sure to run a complete end-to-end test first (forward the work order, have it be rescheduled via the Asset App, forward it again, and complete the work), confirming that the work order is correctly processed in Asset and that the result and signed work order form are also updated in Asset. This ensures that all steps above have been completed correctly and that the integration functions as expected.

Users should download the Spacewell Asset app (search for “Spacewell Asset”) and use the credentials that are provided via:
https://onespacewell.atlassian.net/wiki/spaces/KB/pages/4357490574/Configuration+guide+for+the+Asset+App+integration#5.1-Add-users

Be aware that the email each user automatically receives when the user is created in the Asset App backend will include a link to download the default GoCanvas app. This is not the Spacewell Asset App, which is actually a white-labeled version of the default GoCanvas app (functionally, it is the same and can also be used).

All that is left to do is assign a work order in Asset to a user whose email address matches that of a user in the Asset App backend and who is tagged to the external app in Asset, so that this user receives a dispatch in the Asset App and can handle the work order.

6. Additional information, options, and user guides

For more information about the administrator options in the Asset app backend—including how to create custom forms*, modify the default PDF, manage users, and understand how the Asset app functions for users handling dispatches—please refer to the official GoCanvas documentation:

https://help.gocanvas.com/hc/en-us

*Please be aware of the advice on how to build custom forms as described in Asset App