CMap PSA Project Import (MAIL ONLY)
CMap Mail Project Import Guide
Introduction
As part of your transition to CMap Mail, you may need to do a project import from your CMap PSA instance to CMap Mail, ahead of an email import. This guide provides step-by-step instructions on how to do this, but there is also an accompanying video that provides a useful visual reference.
We recommend that you read this article and watch the accompanying video at least once before you start your project import so that you have an understanding on how the process works. Also, it means you can raise any questions or queries with your CMap Mail Consultant if you need further clarity.
Preparing for your import
Below, we have highlighted some project import prerequisites. We recommend that you action, confirm or follow up on these before you start your import as they may save you time further down the line.
Import Tool
The website that hosts the import tool is password protected. Your CMap Mail Consultant will provide you with this password.
Microsoft 365 Global Administrator Consent
There is a specific import consent that needs to be approved by your Microsoft 365 Global Admin before you start the import. It should have been approved when doing your CMap Mail installation. If you are unsure if this consent has been approved, contact your Microsoft 365 Global Admin or your CMap Mail Consultant.
Integrated Platforms
Your CMap PSA and Mail platforms need to have been linked together via the PSA-Mail integration before you start the import process. If you are unsure if the integration has been set-up, speak to your CMap Mail Consultant.
Windows Machine
The import tool is only compatible with Windows machines.
CMap Mail
CMap Mail will need to have been fully installed before you start the project import process.
CSV File from your CMap Mail Consultant
Your CMap Mail Consultant will have provided you with a CSV with your CMap PSA project information, including the project IDs. It is important you have this CSV before you start this process.
Best Practices & Recommendations
In addition to the prerequisites, here are some best practices and recommendations we suggest you follow or action.
Understand the Process
As mentioned, make sure you read this guide and watch the accompanying video at least once before you start your import. This may remove any blockers further down the line, or answer any questions you may have.
Notify Your IT Team
If you haven't so already, we suggest sharing this guide and the video with your IT team. As we will see later in this guide, you will need to download the importer tool from a website and use the Command Prompt, both of which may need IT approval or review. Letting your IT team know ahead of time what you will be doing is not only best practice, but could also prevent potential roadblocks.
Check Your Command Line
As part of your Onboarding, your CMap Mail Consultant will prepare the Command Line needed for the Command Prompt. We suggest you go through this line with your Consultant ahead of the import to ensure the information they have put together is correct. If any of the information in this line is incorrect, the import will fail.
Test Import
We suggest running a quick test import before you start the main import. This will give you an opportunity to check your set-up is correct and is working as expected.
Permissions
We suggest the person doing the project import has SharePoint admin permissions and is a CMap Mail Admin. This will allow them to carry out a full validation once the import is complete.
Process Overview
The import process can be broken down into 3 key stages. Each stage will contain around 3-5 steps to follow and complete.
Stage 1: Prep
- Prepping the C Drive and import folder
- Downloading the import tool
- Checking the CMap projects CSV file
Stage 2: Run
- Command Prompt Set-Up
- Understanding the Command Line structure
- Running Your Import (& Common Errors and Solutions)
Stage 3: Validate
- Validating the results via SharePoint
- Checking Permissions
- Validating the results via CMap Mail Admin
- Validating the results via CMap PSA
Stage 1: Prep
Step 1: Prepping the C Drive & import folder
-
Open your File Explorer and go to your C Drive. Not sure how to do this? Open your File Explorer > click on the down arrow next to ‘This PC’. You should now see OS (C: ), double click here. This is your C Drive.
-
In your C Drive, create a new folder called 'ProjectImport' (or something equivalent).
Step 2: Downloading the import tool
- Go to this website and enter the password given to you by your CMap Mail Consultant.
- Download the tool called 'Project Creator'.
- Once downloaded, open the zipped folder and extract the files to the new folder you've created in the C Drive.
Step 3: Checking the CMap projects CSV file
- Open the CSV file from your CMap Mail Consultant.
-
The CSV file should have 3 columns:
Column A: CMapProjectId (Your CMap PSA Project IDs)
Column B: Project (Your CMap PSA Project Codes)
Column C: ProjectDisplayName (Your CMap PSA Project Names)
-
Pay close attention to the column titles. Do they match the columns titles seen in the image below? Are there no spaces between words? Are the letter capitalisations correct?
Do NOT change ANY of the information in the CMapProjectId column. This ID number is the link between your CMap PSA projects and your CMap Mail projects. If this is changed or deleted, the two platforms won’t be able to connect to each other.
-
Once your check is complete, ensure the file has been saved as a CSV and saved it the ProjectImport folder in the C Drive.
- Close the file once finished.
Stage 2: Run
Step 1: Command Prompt Set-Up
-
Open Command Prompt. To open Command Prompt, type ‘Command Prompt’ into the windows search bar.
-
Once Command Prompt is open, check that the Command Line is pointing to your user folder in the C Drive.
-
We want the Command Line to be pointing to the folder that contains the import tool and the CMap Projects CSV. To get here, type in cd/ and press enter. This will point the Command Line to the C Drive (C:\>).
Then, type in cd[space][name of folder]. So, if you called your folder ProjectImport, it would look like this:
cd ProjectImport
You'll know if the C Drive is pointing to the right folder as you will see C:\[name of folder]>
Step 2: Understanding the Command Line Structure
- Check the Command Line your CMap Mail Consultant has prepared for you. The structure will look like this:
CreateMailProjects.exe -t [domain name] -i [name of Excel].csv -r Reports -s [SharePoint Tenant Name] -a [CMap Mail Hubsite Name] -v
Let's breakdown what each parameter means:
- CreateMailProjects.exe: Name of the tool with ‘.exe’ added at the end. If you have renamed the import tool at any point in the process, let your Consultant know as they will need to adjust the name in the Command Line.
- -t [domain name]: Found in your email address. The two elements following the @, e.g ‘yourorganisation.com’
- -i [name of Excel file].csv: The name of the CSV file you’ve created with the CMap project IDs, project codes and project names.
- -r Reports: Will generate reports for the import
- -s [SharePoint Tenant Name]: The name of your SharePoint tenant. It can be found in the URL of your SharePoint web address: yourtenancyname.sharepoint.com
- -a [CMap Mail Hubsite Name]: The name of your CMap Mail Hubsite that you created as part of the CMap Mail installation. yourtenancyname.sharepoint.sites/CMapMailHubsite
- -v: Adds additional detail to your reports
So, your Command Line might look something like this:
CreateMailProjects.exe -t CMap.io -i CMapProjects.csv -r Reports -s CMapHQ -a CMapMail -v
The Command Line is very sensitive to spaces so make sure you copy and paste it, rather than typing it out.
There are some optional parameters you can add to your command line, such as ‘create-365-groups’, which will create a Microsoft Team and an Outlook profile, as well as the SharePoint site. If you are considering implementing CMap PIM later down the line, we suggest you include this parameter. You may also want to discuss the other optional parameters with your CMap Mail Consultant to see if there are any others that may be suitable for your organisation.
Step 3: Running Your Import
- Press Enter in Command Prompt to start the import.
- You will be asked to login to your Microsoft 365 account. Select the relevant account and wait for the 'Authentication Complete' message to appear. You may need to do this two times The login page will stop appearing automatically once the authentication is complete. This ensures the import tool can establish the correct tokens.
- Head back to Command Prompt.
If the import has been kicked off successfully, you will see the following statuses:
Preparing or Updating Project Site: The import tool has identified projects to create or update.
Creating Project Site: The import tool is creating new project sites or updating existing ones.
Adding Site to your CMap Mail Hubsite: The site is being added to the CMap Mail Hubsite.
Site Created Successfully: The project site has now been fully created or updated.
Once the import tool has completed one project, it will automatically move onto the next one on the list. You can minimise Command Prompt, but do not close it as this will stop the import.
Common Errors & Solutions
The errors will appear in this format on the Command Prompt:
| Error Message | Cause | Solution |
|
| "Unable to get Graph Client" | Authentication failure | Check tenant name and permissions | Diagnosis Steps:
|
|
| "Failed to get hubsite id" | Hub site not found | Verify hub site name and access | Diagnosis Steps:
|
|
| "Reading csv file FAILED" | CSV format issue | Check file format and encoding | Diagnosis Steps:
|
|
| "Failed to prepare site" | Site creation failure | Check permissions and site limits | Diagnosis Steps:
|
|
| "Failed to prepare site" | Site creation failure | Check permissions and site limits | Diagnosis Steps:
|
|
| "Failed to configure site" | Post-creation setup failure | Verify security groups exist | Diagnosis Steps:
|
Stage 3: Validate
Step 1: Validating via SharePoint
- To check the results of the import, you can validate via SharePoint. Using this URL format: https://[yourSharePointTenant].sharepoint.com/sites/[projectcode] to see if a project you imported has been created successfully. Make sure you remove the square brackets and add in the required information.
Step 2: User Permissions
- While on the SharePoint site, you can check if the user permissions have been correctly assigned to the project.
- In the top right-hand corner, click where it says 'X Members'.
- When you expand Site Owners, we want to see the CMap Mail Admins group. This will allow the CMap Mail admins to add other users to the project
- When you expand Site Members, we want to the CMap Mail All Users group. This will allow the users in this group to file into the project via the CMap Mail plugin.
Step 3: Validating via CMap Mail Admin
If you can't access the Admin Centre, make sure you are a CMap Mail Admin.
- Go to the CMap Mail Admin Centre.
- Once logged in, see if you can search and find some of the projects you imported. Make sure the correct project codes and names are showing.
Step 4: Validating via CMap PSA
- Go to your CMap PSA instance.
- Find a project that was imported to CMap Mail .
- Open it and click on the 'Mail' tab (you may need to click on the 3 dots in the right-hand corner).
- After logging in, the tab should open directly to the CMap Mail project. Note: You SHOULDN'T see the 'Select a Project' field as the two platforms are linked together.
If the tab doesn't open directly to the CMap Mail project or if you are unsure if your CMap PSA and Mail platforms have been linked, contact your CMap Mail Admin.
Import Complete
You have now completed a project import from CMap PSA! If you ran into any problems, or have any questions, contact your CMap Mail Consultant.