Skip to main content
Procore (en-GB)

Migrating Data Connection Apps to Use Developer Managed Service Accounts

 

 deprecation of traditional Service Accounts
Traditional Service Accounts will be deprecated on December 9, 2021. Creation of new traditional service accounts will no longer be allowed after July 31, 2022. All traditional service accounts will be sunset on January 31, 2023. As a result of this deprecation, developers of data connection applications that currently use traditional service accounts must migrate the app to use DMSAs and customers must install these migrated apps before the January 31, 2023 sunset date. See Deprecation of Traditional Service Accounts for more details.

Objective

To migrate an existing data connection application that uses a traditional service account to a new version that uses a Developer Managed Service Account.

Background

With the deprecation of traditional service accounts and the release of Developer Managed Service Accounts (DMSA), customers currently using data connection applications that rely on traditional service accounts must plan to switch over to using applications that use DMSAs prior to the January 31, 2023 sunset date. Third-party developers and integrators will be updating their applications to use DMSAs and make new versions available to Procore customers over time. This tutorial provides some suggestions for preparing a migration plan and outlines the procedures for working through a migration.

Things to Consider

  • Required User Permissions:
    • Company Admin

Migration Preparation

Understanding your existing traditional service accounts can help you plan effectively for a successful application migration. Before migrating to a DMSA application you will need to review the settings for each of your existing service accounts to verify the information is accurate and to update any service accounts where the settings may be missing or incorrect.

Service accounts are categorised into two application types - `Marketplace` and `Custom`.

  • Marketplace - for service accounts that are mapped to applications installed from or listed on the Procore App Marketplace. Applications are selectable from a dropdown list.
  • Custom - for custom applications that were developed internally or by third-party integrators specifically for your company.

Note that some service accounts in your company may not have a defined application type. You will need to update these service accounts with the correct application type before migrating to DMSAs. It is also a good opportunity to review and verify the existing application type settings to ensure your service accounts are mapped properly.

Step 1 - Set Application Type for Undefined Service Accounts

Use the following steps to update your existing service accounts where the application type is not defined.

  1. Navigate to the company's Admin tool.
  2. Under 'Company Settings', click Service Accounts. The Service Accounts page shows a list of the existing service accounts in your company.

existing-service accounts.png

Upon examining your service accounts you may see one or more accounts with no value in the App Name column, as shown in the first account in the example above. This indicates that the application type for that service account is undefined. You will need to update those accounts before migrating to DMSA.

  1. Locate a service account where the App Name column value is missing and click Edit.

service-account-app-type.png

  1. For the App Type setting, choose one of the following options:
  • Marketplace - choose this setting if the service account is mapped to an application on the Procore App Marketplace. Use the dropdown menu to select the application. Verify that the application you select matches the application you have in production.

edit-account-marketplace.png

  • Custom - choose this setting if the service account is used by an application you have developed internally or by an application built by a third-party integrator specifically for your company. Enter a description for the account as well as the developer name and email address.

edit-account-custom.png

  1. Click Update.
  2. Repeat Steps 3-5 above for all existing service accounts in your company where the App Name column value is missing.

Step 2 - Review and Verify Existing Service Account Mappings

Now that you have set the application type for all your existing service accounts, take a few minutes to review each account and verify that the application type mapping is correct and that all required fields and are filled in as needed.

Review Custom Service Accounts

  • Be sure that all service accounts marked as `Custom` are actually used by custom integrations rather than by Marketplace applications. If you find a Custom service account that should be changed to a Marketplace account, update the App Type setting as described in the previous section.
  • Verify that all Custom service accounts in your company are actively being used. Remove any inactive accounts.
  • Verify that all Custom service accounts in your company have the DescriptionCompany/Developer Name and Company/Developer Email fields filled in accurately. (see above)

Review Marketplace Service Accounts

  • Be sure that all service accounts marked as ‘Marketplace’ are actually used by applications from the Procore App Marketplace that you have currently running in production. If you find a ‘Marketplace’ service account that should be changed to ‘Custom’, update the App Type setting as described in the previous section.
  • Verify that all Marketplace service accounts have the correct Marketplace App selected in the dropdown. (see above)

Migrate Applications to DMSA

The steps for migrating an application from traditional service account to DMSA varies depending on the application type.

Marketplace Applications

  • Reach out to the developers of your existing service account based Marketplace applications to understand when they expect to have DMSA-enabled versions available for their customers. Locate the application listing on marketplace.procore.com and use the developer email or support information to contact the developer.
  • Formulate an internal communication plan based on the release dates provided by the developer, so that your end users are informed about any pending application migrations. Include timelines for moving all users onto new applications and for retiring the old versions.
  • Once the DMSA-enabled version of the application is available, follow the steps outlined in Install a Data Connection App from the Marketplace. If you are unclear about how to install the new DMSA-enabled version of a particular application, contact the developer for additional information.
  • After successfully installing the new Marketplace application, instruct your end users to begin using the new application instead of the older version.
  • After all users have been successfully moved over to using the new application, you can remove the old service account as described in Delete a Service Account and uninstall the old version of the application.

Custom Applications

  • If a custom application was developed and maintained internally by your company, you will need to develop a new DMSA-enabled version of the application as described in the Service Account Deprecation announcement. See Developer Managed Service Accounts for details. Reach out to apisupport@procore.com if you need additional guidance.
  • If a custom application was built by a third-party developer specifically for your company, reach out to them to understand when a new DMSA-enabled version of the application will be available and make sure they fill in the custom application information on the Service Account user interface.
  • Once the DMSA-enabled version of the custom application is available, follow the steps outlined in Install a Custom App. If you are unclear about how to install the new DMSA-enabled version of a particular application, contact the developer for additional information.
  • After successfully installing the new custom application, instruct your end users to begin using the new application instead of the older version.
  • After all users have been successfully moved over to using the new application, you can remove the old service account as described in Delete a Service Account and uninstall the old version of the application.