Newforma Connector Knowledge Base

Helping to Support Newforma Customers

Refer to this KB article when customers report issues with the Newforma <> Procore connector.

• How do I contact Newforma Support?
• How do I read the App Xchange logs? - What does each service do? It is important to understand the direction of data transfer.
• Help! Items do not sync as I expected - Common scenarios like invalid project mapping, unable to connect a project, or missing attachments.
• Newforma API Errors - 401, 403, 404, 409, 500, 502, 503, 504 response codes, and contacts or lists removed from NPC
• Procore API Errors - Reauthorize, 400, 403, 429, 503 response codes, and missing info on Procore-side
• Other Issues or Failing Syncs - Check the status page to see if Trimble is having service disruptions

How do I contact Newforma Support?

A customer should always contact Newforma Support first. Newforma will loop in Trimble behind-the-scenes as needed.

How do I read the App Xchange logs?

Here is what each of the services do. It is important to understand the direction of data transfer. 

Newforma Cache Writer (Newforma -> Trimble)

The Newforma Cache Writer sends updates from Newforma to Trimble. Trimble makes calls to the Newforma API to look for new data or changes to data. This is the most common area for failures and usually does not self-heal. Failures are in the Newforma API and the response will indicate what is wrong. See the “Newforma API” section below for more information.

Newforma SI Action Processor (To Newforma)

The Newforma SI Action Processor updates Newforma from Trimble ie. Trimble -> Newforma. The actions this service completes:

• Actions are handled when it runs.
• If the actions are not successful, an error will be logged.

Procore Cache Writer

The Procore Cache Writer is Procore -> Trimble. Trimble makes calls to the Procore API to look for new data or changes to data. Failures in the Procore API are less common and the response will indicate what is wrong.

Procore Action Processor

The Procore Action Processor is Trimble -> Procore. Trimble makes a call to transfer data to Procore. Failures are not common, but the response will indicate what is wrong.

Event Processing

These are internal to Trimble and means Trimble is processing inside the Trimble platform. Some use-cases will email the BIC that data did not transfer and provide a message why.

Help! Items do not sync from Procore to Newforma or back to Procore from Newforma

Follow these steps:

1. Check the customer in the Trimble App to make sure the sync schedule is enabled.
2. Allow a few minutes after you enable the sync. It can take several minutes to complete because it needs to grab contacts, keywords lists, projects, Submittals, RFIs etc.
3. The connector will not move over any items if it finds a manually created item with the same item ID number.
4. Check the business rules in Procore: 
   1. item in an Open status.
   2. Ball in Court (BIC) user on the items match the Ball in Court set in the Trimble Partner Portal
   3. BIC user in the Project Directory in Procore AND in the Project Team in NPC
5. Check for an invalid project mapping. See section below.

Check for Invalid Project Mappings

It is always a good idea to check for a valid project mapping. If data does not transfer between Procore and Newforma, simply log in to the CDX Registration Website (the partner portal).

1. Search for or find the project you are working on.
2. Click the icon to view the current project mapping.
3. If there are any blanks or invalid mappings, then fill out the page and hit save.
4. Now data will transfer moving forward.

Customer may have adjusted submittal responses and broken any mappings that are associated. If changes are made to submittal responses, the mappings using those responses are not updated, they simply break and become invalid.

What steps should Newforma Support take when a customer is unable to connect a project?

When the user clicks a button in NPC, it will launch the CDX Registration Website (the partner portal). This website is maintained by Trimble. Credentials to log in are provided during onboarding.

Once logged in, the user is taken to a transition page to connect their project. If successful, they can fill out the project mapping. If unsuccessful, here are some common errors:

• A message will be displayed if the access key and secret for the Newforma API is invalid. If you see this message about invalid credentials, then review the access key and secret to make sure they were typed in correctly.
• Customer is getting "Company X does not allow connections from outside applications. Contact Procore Support." message when trying to link a project. This is because the contractor admins have blocked apps from registering on their account. Admins need to add Newforma app in Procore app store to their account.
• Can’t find Newforma project - Project does not exist within Newforma. The access key and secret are saved correctly, but the underlying service account on the Newforma side for that access key does not have permissions to the project. Need to troubleshoot the permissions first as those are most likely the cause.

What steps should Newforma Support take when a customer says that files did not transfer?

Short Answer: They should troubleshoot the Newforma API logs.

Attachments from Procore are grouped to be transferred inside a zip file and that zip file is sent. There may be reasons the customer does not want this zipping behavior; mobile devices are one use-case that struggles with unzipping. File extraction is enabled for most customers that will unzip these files for the customer. If the integration is unable to expand the zip it will simply send the zip file.

The Trimble job log will NOT show the underlying error. It will simply show you that the event processor was unable to get a file from Newforma or Procore and that it transferred data without the file. The customer was notified via email.

Newforma should reach out to their own resources to troubleshoot the customer's logs and see why a file is not available. Trimble cannot troubleshoot this and cannot see the root cause.

Newforma API Errors

This is the most common area for failures and usually does not self-heal. Failures are in the Newforma API and the response will indicate what is wrong.

Compatibility errors

503 service unavailable error “Unable to verify if this version of NewformaApi 'xxxx' is compatible with NPCS version 'xxxx', because the server is offline” or "This version of NewformaApi 'xxxx' is not compatible with NPCS version 'xxxx'".

Both errors point to a compatibility problem between the Newforma API and NPCS versions. All of the customer’s NPCS need to have the same versions of the NPCS, Newforma Link, and Newforma API applications installed. Further both Newforma Link, and Newforma API applications MUST be compatible with the NPCS version.

Code cannot be run, the compiler emitted errors

1. Login to the NPCS as the service account.
2. Stop all Newforma services.
3. Close NPC, the Tray Tool, and Outlook.
4. Go to Task Manager and close the Viewer.exe process.
5. Open a Command Prompt as admin and run IISRESET /STOP. Leave the window open.
6. Delete the folder located at %LOCALAPPDATA%\Newforma\DynamicCode.
7. Run the command IISRESET and confirm in the Command Prompt that IIS restarted successfully.
8. Start all Newforma services

Newforma API: 401 Unauthorized

Often an authorization issue and often occurs in Kerberos. The error indicates the unique user for Newforma API (the Newforma API user) does not have correct delegation. In some cases you may need to reassign the identity used on AppPool when viewed in IIS manager.

Check the API user account's access (the account tied to the Newform API access key and secret).

1. Logon to the NPCS as the service account. In the Command Prompt run IISRESET.
2. Kick off a manual sync. Allow 1-2 minutes then check the Trimble logs to see if the issue ceases.
3. If the error continues, assign projects in NPC to this user's My Projects list.
4. Login to Newforma Cloud as the API user and click the project tiles to open each of the projects.
5. Drill-down into the project folders to confirm the user has access to the Record Copies folder.
6. Did you encounter any error in Newforma Cloud? Troubleshoot them.
7. Check if MFA is enabled on the (Newforma API) user account and disable it, then run IISRESET and test.

If the issue continues run the Swagger test for the Newforma API:

1. Login to the NPCS as the Newforma API account.
2. Launch a browser, navigate to this path: http://localhost/newformaapi. This will open the Swagger website.
3. Test the following endpoints to confirm the Newforma API is functional.
   1. Health - this should return a 200 in the Response Code field.
   2. Projects - this will retrieve all the projects though the API will only display 1500 projects. A line will indicate the total number of projects.
   3. Version - this will display the compatibility between the NPCS and Newforma API versions.
4. Test the same endpoints using the external URL to verify no errors occur from the Azure AD App Proxy. The External URL can be obtained from Azure on the NPCS's Enterprise App > App Proxy settings.
5. If the issues continue, check the Event Viewer for the App Proxy logs and look for any errors that match the time of your testing.

Newforma API: 403 Forbidden

This is a permissions issue. Check the API user's access. This is the service account tied to the Newform API access key and secret.

1. Logon to the NPCS as the service account user. Open the Command Prompt as Admin and run the command IISRESET.
2. Kick off a manual sync in the Trimble App. Allow a few minutes then check the logs to see if the issue ceases.
3. If the errors continue, assign projects in NPC to this user's My Projects list.
4. Next login to Newforma Cloud as the API user and click the project tiles to open each of the projects.
5. Drill-down into the project folders to confirm the user has access to the Record Copies folder.

Newforma API: 403 Permission to project denied

The Trimble Portal logs will show an error similar to: forbidden. This often occurs on a Confidential project in Project Center. Make sure the "Newforma API" user is a member of the project team and has Read/Write/modify access to the project data on the file server.

Newforma API: 403 Missing CA Role in NPC

If you see an error “User does not have contract administrator role”, help the customer add that role in NPC.

Newforma API: 404 Not Found

If Newforma Cache Writer is failing on a specific submittal or RFI with a 404 message. The customer has deleted this from Newforma, so now Trimble has to wipe it from the cache. This is done automatically by the integration and should not require manual intervention.

If the issue continues, follow these steps:

1. Check App Monitoring and make sure the Newforma Link AND Newforma API is installed on ALL of the customer's NPCS. If they have multiple servers, regardless of where the connected project is located, make sure these apps are installed on all of them.
2. Login to the NPCS as the Newforma API account.
3. Launch a browser, navigate to this path: http://localhost/newformaapi. This will open the Swagger website.
4. Test the following endpoints to confirm the Newforma API is functional.
   1. Health - this should return a 200 in the Response Code field.
   2. Projects - this will retrieve all the projects though the API will only display 1500 projects. A line will indicate the total number of projects.
   3. Version - this will display the compatibility between the NPCS and Newforma API versions.

1. Open the Cloud Readiness dashboard. Locate the customer and go to the second page to obtain the External URL. They can also obtain the External URL from Azure on the NPCS's Enterprise App > App Proxy settings.
2. Test the same endpoints using the external URL to verify no errors occur from the Azure AD App Proxy. 
3. If the issues continue, check the Event Viewer for the App Proxy logs and look for any errors that match the time of your testing.

Newforma API: 404 There is no valid endpoint for Client

Single GET failed for project with Id-Number ae49bd7a...– 404){"type":"http://issues.newforma.cloud/common/not_found","title": "There is no valid NL endpoint for Client"}.

This error can occur when there is an issue with Newforma Link or the Newforma Cloud config on the NPCS. The error identifies the Connector is unable to retrieve info for the project listed in the error and suggests a potential config issue with Newforma Cloud on the server. This is common when a new NPCS is set up but Newforma Cloud is not yet deployed. 

To resolve the issue:

1. Make sure each NPCS is configured for Newforma Cloud. If this is not possible, remove Newforma Link from the server hosting the project with the error.
2. Force a resync for the customer and check the Trimble logs to see if the error continues to occur.
3. If the issue still occurs, try to login to Newforma Cloud as a user that has the project added to their My Projects list. 
4. Click the project tile to confirm if you can access the project or if there is an error in the Newforma Cloud config on the server.
5. Continue to troubleshoot Newforma Cloud on the new server.

Newforma API: 409 Conflict The request could not be completed due to a conflict with the current state of the target resource.

This error code displays in the IIS logs when there is a failure. It indicates Newforma API has a conflict completing the request due to a business rule failure. An example is when an item already exists in Newforma:

Posting Submittal to Newforma API for project ca30a07f-a1d0... (ActionId: 9c23e66c...) was unsuccessful: {"type":"http://issues.newforma.cloud/common/conflict","title":"{\"ErrorMessage\":\" already exists: 22 4000-100-1\"}"}

There can be other unknown causes.
To confirm the issue
1. Launch a browser and login to Newforma.Cloud as the Newforma API user.
2. Launch NPC and click Project Center Administration > Licensing tab.
3. Click the Newforma API user and edit the user's My Projects by adding the project connected to Procore.
4. Save the changes,
5. Allow 1-2 minutes and refresh the page in Newforma.Cloud and confirm the new projects appear.
6. Click the projects and confirm you can navigate the folder structure.
7. If you get any errors in Newforma Cloud, login to the NPCS, start the Command Prompt as an Admin and run the command: IISRESET.
8. Go back to Newforma Cloud and refresh the page to confirm it loads correctly.

Newforma API: 500 Internal Server Error

An issue with the Newforma API is causing it to be down for some or all endpoints. Their server could be offline due to a power outage, maintenance, security breach, recent upgrade, or any other reason, so contact customer to learn more.

Newforma API: 502 Bad Gateway

When this error occurs check the following:

1. Check the status of the customer's App Proxy. 
   1. To test, first get the External URL for the NPCS that has the issue.
   2. Paste the External URL into a browser on the NPCS. When prompted to login, login as the Newforma user first. If this works login and test as the Newforma API.
   3. When the test is successful the IIS landing page will display. If there are errors, continue below...
2. Verify with the customer if any changes were made in their environment, especially to firewall, server updates, security, or similar changes. If changes to the firewalls were made, provide the customer with the list of addresses to whitelist for the App Proxy.
   
   If no significant changes were made to the customer environment, login to the Azure portal (portal.azure.com) to check the status of the App Proxies.
3. Go to Azure > Azure Active Directory > Application Proxy and review the status of the App Proxies.

Note: We recommend the app proxy on each NPCS. Additionally, assign the app proxy to its own Connector Group.

1. If the status is not Active, go to the server hosting the App Proxy and stop then start the two app proxy services: Microsoft AAD Application Proxy Connector and Microsoft AAD Application Proxy Updater. 

2. Allow 1 to 2 minutes then refresh the Application Proxy page in the Azure portal to see if the app proxy is active.

3. If the issue continues, start the Command Prompt as an Admin and run the command: IISRESET.

4. Continue these steps for each NPCS (or server on which the app proxy is installed).

5. Go back to the Azure portal, refresh the page and check if the App Proxy is active.

6. Try the External URL test once again to check for errors. If there are still errors, capture the errors and search this document for a solution.

   If there aren't errors, continue below.

7. ​​​​​Login to Newforma.Cloud as the Newforma API user and confirm you are able to peruse the folders for the different projects. If this step is successful it means the Azure AD App Proxy is functional.

8. If the issue continues check the App Proxy logs on the server hosting the app proxy and look for any errors to help identify the root cause.

9. Open Event Viewer and look for Application Proxy connector events in Applications and Services Logs > Microsoft > AadApplicationProxy > Connector > Admin

10. Check the status of each App Proxy in Azure AD to ensure each is functional.

IMPORTANT: If the server has continual issues with chronic App Proxy failures consider installing the App Proxy on another server in the same location in the customer environment.  

Newforma API: 503 Service Unavailable

503 errors can occur when there is an issue with the Newforma API. To test the Newforma API:

1. First, ensure the exact same version of the Newforma API is installed on all NPCS.

2. Next, using the Swagger tests, confirm the API functions correctly. Follow these steps to test internally and externally. Note: to test Newforma API, use this URL: http://localhost/newformaapi How to run the Swagger Tests for Newforma Link.

3. Your next steps are determined by the output of these tests. If the internal Swagger test fails with the 503 Service Unavailable error, uninstall the Newforma API, then reinstall it (install the version compatible with your version of the NPCS) and try the internal Swagger test.

4. If the Swagger tests are successful, uninstall then reinstall the Newforma API from all other NPCS in the customer environment.

5. Ask the customer to verify by testing in Procore to verify internal and external actions from the Newforma API function.

6. Be sure to re-enable the Procore Sync once the issue has been resolved.

If the issue continues, review the Newforma API logs and IIS logs from the server and look for errors. Run IISRESET again, and test once more.

Newforma API: 504 Gateway Timeout

This indicates a connectivity issue in the MS AAD App Proxy Connector or in a missing Procore Connector related component. 

Check the following:

1. Make sure Newforma API iand Newforma Link are installed on each NPCS

2. Open the Command Prompt as Admin on the NPCS and run IISRESET. Confirm IIS restarted correctly.

3. Wait 15 minutes to see if the items come through.

4. If the issue continues, stop the Microsoft AAD App Proxy Connector service. Allow 15 seconds, then start it again.

5. Run IISRESET again and confirm IIS restarted correctly. Wait 15 minutes to see if the items come through.

6. If the issue continues to occur, reboot the NPCS.

7. When the server is back online, check the Trimble Portal logs for errors to determine if there is still a 504 error or if another error occurs, then troubleshoot.

8. If there are still 504 errors, check the App Proxy logs on the NPCS for errors.

9. Open Event Viewer and look for Application Proxy connector events in Applications and Services Logs > Microsoft > AadApplicationProxy > Connector > Admin.

10. Check the status of each App Proxy in Azure AD to ensure each is functional

Customer deleted ALL BIC users from NPC

Customer deleted their Newforma contact record. Newforma Support needs to contact customer to add themselves back to NPC or re-link all projects to a different BIC user.

IContactRows: Customer deleted the BIC user from NPC, but another exists with the same email

Error: Posting Submittal to Newforma API for project was unsuccessful: IContactRows not found

Customer will report that data is no longer transferring into NPC for their BIC. You’ll see IContactRows error in the log. This means the customer deleted their user account from NPC, but there is another one in NPC with a different ID. Contact Trimble Support to fix. Trimble will remove the deleted user and since there is another user with the same email, the integration will use that instead and it will work.

Customer Deleted the Global Action List in NPC

Newforma refers to this as the Global UAC Submittal Action List. Only Respond and Close types are shown. The Name must be unique for the type. So you can't have two Respond and Close types called For Record Only. There can be only one per type.

The log will show you the list name that is missing or invalid. Work with customer to configure NPC so it can work with the integration. They have deleted something that is required by the integration.

Action with keywordListName: RFI Action List and keywordName: xxxx was not found

This error can occur for RFI or Submittals when the Action List Keywords for the project are missing a keyword. Generally, this error affects only the activity with the missing keyword.

To resolve the issue

1. Check the project settings, Keyword list assigned to the specific activity (RFI or Submittal).

2. Once you identify the keyword list, go to Project Center Administration > Keywords tab then modify this keyword list.

3. Add the keyword referenced in the error.

Procore API Errors

Errors in the Procore Cache Writer indicate the Connector has difficulty reading info from Procore. You will often see in the Trimble logs multiple entries for the Procore Cache Writer, one entry per Ball in Court user. This confirms the particular user has the issue.

There are only a handful of Procore Cache writer errors. Here are the most common:

Expired Tokens or Invalid Signatures - Reauth

Expired tokens and invalid signature error messages mean a Re-authorization is needed – You will see an oauth message. A daily report detects these and provides the links to Newforma Support. Newforma Support can help customers click a link (that is specific to them) to re-authorize.

Procore API: 400 Bad Request

Trimble must look at the response from Procore and why they think it is a bad request. It is most likely an invalid project status mapping. This can occur when the customer has deleted, duplicated, or renamed a submittal or RFI status and the project will need to be remapped.

1. Login to the Partner Portal - go the Project Settings in NPC > Admin tab and click Configure to launch the portal website.

2. Search for or find the project you are working on.

3. Click the icon to view the current project mapping.

4. If there are any blanks or invalid mappings, then fill out the page and hit save.

5. Now data will transfer moving forward.

Procore API: 403 Forbidden

403 forbidden/permissions errors, because the user no longer has access to the connected project. Since the permissions issue is on the Procore side, have the customer check for the permissions required by the integration.

Customer account is active, but they don't have permissions in Procore to do what we want:

• An error occurred when trying to get Rfis from Procore: {"errors":"You do not have sufficient access to complete that action."}

• An error occurred when trying to get submittal responses from Procore: {"errors":"You do not have sufficient access to complete that action."}

Reach out to customer and ask them to review why they no longer have permissions to this project. If they need permissions, add to the project team and make sure the project is not confidential. If that user no longer needs permissions, then please unlink this project via the portal.

 

Is the customer’s Procore account active? Or was it deleted entirely?

Example: An error occurred when trying to get submittal statuses from Procore: {"error":{"code":"FORBIDDEN","message":"This account is inactive"}}

Reach out to customer and ask them to review why the account is deactivated. If that user no longer needs permissions, then please unlink this project via the portal.

 

What does the "invalid project or company" errors mean?

These errors in the Procore CDX Cache Writer mean the user has lost permissions to the project in Procore.

• Error occurred when trying to get Project from Procore: {"message":"Item not found"}

• Error occurred when trying to get Submittals from Procore: {"message":"Invalid Project or Company"}

• Error occurred when trying to get submittal responses from Procore: {"message":"Invalid Project or Company"}

• Error occurred when trying to get Rfis from Procore: {"message":"Invalid Project or Company"}

• The "invalid project or company" errors sometimes can be specific to a user for specific projects. We can infer from this that at one time the user had permissions to the project in Procore and was able to connect it to Newforma. However at some point the user has lost access to that project.

The "invalid project or company" errors usually come in groups of 4 or 5. They will occur every sync until the permissions are fixed in Procore OR the project is disconnected. Trimble cannot find the project in Procore, we cannot access submittals, submittal responses, or RFIs on the project, because the user no longer has permissions to it in Procore.

To resolve

1. Ask the customer to check their permissions to the Procore project. The user likely recently lost permissions to the project in Procore. Recommend customer to check the project in Procore. Once they regain access to the project, the data will flow automatically.

2. If customer is unresponsive, or if customer responds that they no longer needs access to the project, click "Disconnect Project" at the bottom-right when loading the project configuration page.

3. Do not reach out to Trimble to disconnect projects. Instead train the customer how to login and disconnect their projects. Only reach out to Trimble to disconnect projects if the customer is unable to do so via the portal.

Procore API: 429 Too Many Requests

Procore hourly rate limits are being reached. Stop sync and wait 1-hour. Then run the sync again.

Procore API: 503 Service Unavailable

Trimble will attempt to process the action again. It may go through. If you see this for long periods of time, you can open a ticket with Procore to look into their API, but that hasn’t been too helpful. Luckily, errors in the Procore API are not common, but they have outages too.

Missing required info in Procore or NPC

If you see a message about failed to find a submittal response ID or RFI ID, then the customer has removed some required information in NPC or Procore. The error should say what is missing, so reach out to them and have them add it back.

App is not connected to this company

The App is not connected to this company error means that the Procore project has not added the Newforma app to their Procore account. Please contact the customer so they can work with their Procore admins to add Newforma app in Procore app store to their account.

NOTE: Since the permissions issue is on the Procore side, the customer should direct the user identified in the error to:

1. Login to Procore and confirm they see their projects.

2. In each project check the RFI and Submittals logs to ensure the user still has access. If there is an issue, check for the permissions required by the integration. Make sure their Procore user has permissions to submittals and RFIs.

Other Less Common Things

Long file name or blank name

• Very long file name.

• Very long subject/title/submittal number.

• Subject/title/name is blank. These things are required and will be rejected.

Cancelled or Failing Syncs

When a customer has a chronic issue with the syncs appearing to get cancelled and not complete, they likely have too much data for it to be set at every 15-minutes. The sync is often taking longer than 15-minutes and that's why you'll see so many cancelled runs. If a run is about to overlap, it will be marked cancelled so a new one can begin.

It could be an unknown error in Trimble platform, rare, but possible outage at Trimble.