Skip to main content
Cartegraph Campus

Cartegraph Remote Data Transfer Utility

Feature Description

The Remote Data Transfer service moves a file from/to an on-premise system to/from the Cartegraph Project Home. It can be scheduled to run at a specific interval via the Windows Task Scheduler. The service is called Cartegraph.RemoteDataTransfer.exe.

Log files record the activity of the Remote Data Transfer utility.

System Requirements

This section describes the requirements for the installation and use of the Cartegraph Remote Data Transfer utility. This utility can be used with Cartegraph version Spring 2015 or later. The utility may be installed on a workstation or a server with the following requirements:

Customer Workstation

Software

.NET version 4.5 or later

Windows Task Scheduler

Operating System options

Windows 7 Professional or Ultimate editions 

Windows 8.1

Other

All Microsoft updates must be installed

Internet Access

Server

Software

.NET version 4.5 or later

Windows Task Scheduler

Operating System options

Windows Server 2008 R2

Windows Server 2012

Windows Server 2012 R2

Other

All Microsoft updates must be installed

Internet Access

Implementation

Complete the following steps to deploy the Remote Data Transfer utility:

  1. Copy the following files from the RemoteDataTransfer folder and paste them all into a single directory:
    • Cartegraph.RemoteDataTransfer.exe
    • Cartegraph.RemoteDataTransfer.exe.config
    • RestSharp.dll
  2. Open the file Cartegraph.RemoteDataTransfer.exe.config.
  3. Set the value for CartegraphURL inside the quotation marks. This is the full Cartegraph URL site.
    1. Change the value for the NumberOfAttempts and MinutesBetweenAttempts.

  4. Save and close the .config file.

Authenticate to Cartegraph

Before the utility can be run, the user needs to be authenticated with Cartegraph. The /username and /password arguments are both required as part of the command.

To authenticate the user:

  1. Determine the user that will be used.
    1. The user needs to have Cartegraph Link/Upload Attachment global permissions set to Allow or Allow and Custom. They also need permission to Import/Export in Administration.

    2. Cartegraph recommends creating a user for this process with only the security to Link/Upload Attachments and Import/Export.  Never use the default Admin user account.

  2. Open a command prompt and go to the folder directory where the utility resides.
  3. Enter the command to authenticate the username and password with Cartegraph using the example below. For example:
    1. RemoteDataTransfer.exe /username:username /password:password
  4. Verify that the following messages are returned.
    • Remote Data Transfer Program Started
    • Remote Data Transfer Program Completed Successfully.
  5. Close the command prompt screen.
  6. Validate in Cartegraph.RemoteDataTransfer.exe.config that the encrypted strings for username and password are updated.
    1. This is a one-time setting. The Utility uses the credentials from the .config file.

Schedule the Service

  1. Open the Windows Task Scheduler.
  2. Select Create Task and give it a name.
  3. From the Actions tab, click New.
  4. Verify the Action is Start a program.
  5. In Program/script, browse to Cartegraph.RemoteDataTransfer.exe and select it.
  6. In the Add arguments field, enter /upload argument or /download argument:
    1. /upload argument contains:

/file (required). The full-path of the file to upload to the project home.

/serverlocation (required). The file API URL for the import/export appended with the file name you are saving as in the Project Home import/exports folder.

/deletefileafterupload (optional)

Example Argument:

  1. /upload /file:"C:\DataUpload\Data.csv" /serverlocation:"https://MY_URL/Cartegraph/api/v1/fil...xport/Data.csv"
  2. /download argument contains:

/file (required). The location where you are downloading the file to from the Project Home and the name of the file you want to save it as. 

/serverlocation (required). The full API URL for the import/export appended with the file name you are downloading from the Project Home import/exports folder.

Example Argument:

  1. /download /file:"C:\DataDownload\Tasks.csv" /serverlocation:”https://MY_URL/Cartegraph/api/v1/fil...port/Tasks.csv"
  2. In the Start in field, enter the directory location of the Cartegraph.RemoteDataTransfer.exe. This is where the logs are created.
  3. In the Triggers tab, select the desired settings to schedule the task.
  4. Click OK to close the Create Task window and save the new task.
  5. If you choose to run the task immediately, in the Task Scheduler, right-click on the Task name in the library and select Run. Otherwise, the task runs according to your Trigger settings.
  6. Since the authentication of the user was done through a command prompt, the utility runs as a scheduled task without the manual entry of the sign in each time.

Update User Credentials

If the Cartegraph user associated with the utility needs to be changed for any reason, re-run the authentication from the command prompt as documented above.

Upgrade Instructions

There are no upgrade instructions necessary for this service to persist through Cartegraph Software upgrades.

Appendix

Input Arguments

/username

Process Indicator that username will be updated. SEE "Authenticate to Cartegraph."

/password

Process Indicator that password will be updated. SEE "Authenticate to Cartegraph."

/upload

Process Indicator that a file will be sent from the server to the project home.

/download

Process Indicator that a file will be brought from the project home to download the server.

/file

The fill path of the file to be uploaded or downloaded to. Must include the file name.

/serverlocation

The server location path the file will be uploaded to or downloaded from. Must include the file name. The location must be in the Cartegraph Project Home import.export folder. For upload, if an existing file is encountered in the drop location, the utility will stop with errors. For download, the file will be overwritten if the file already exists. 

/deletefileafterupload

This is an optional argument for the /upload command only. Determines if the source data file is deleted after the command is completed. If the argument is not supplied, the file is not deleted. The file will only be deleted if the upload completed successfully. 

Executable Config File Settings

CartegraphURl

The base URL to the Cartegraph site.

CartegraphAuthURL

The URL path to the API authentication method.

NumberOfAttempts

The number of tries attempted once an error is encountered sending the file.

MinutesBetweenAttemptes

The number of minutes to wait when an error is encountered transferring the file before trying again.

CartegraphUsername

The encrypted username to authenticate the connection to Cartegraph. Do not manually add this setting.

CartegraphPassword

The encrypted password to authenticate the connection to Cartegraph. Do not manually add this setting. 

Log Files

Log files are created the first time the Remote Data Transfer utility runs. The logs exist in the same directory as the executable file and are appended to each time the Remote Data Transfer utility runs. Entries in the log files have date/time stamps of the activity start, stop, errors and success of processing.

A log file is created by the Remote Data Transfer utility itself. This file is named Cartegraph.RemoteDataTransfer_Log.txt. Another file is also created with the name of the uploaded or downloaded file followed by _Log.txt. For example, if the file being uploaded is Meter.csv, the log file will be Meter.csv_Log.txt.

Remote Data Transfer log file will record the date/time that the utility started, if it is doing an upload or download, and date/time that the utility completed. If there were errors, it will record that it completed with errors and the user should refer to the log file for the specific file being uploaded or downloaded. In some instances, if the utility failed for something unrelated to the file being uploaded or downloaded, the errors may be recorded in the Remote Data Transfer log file only. An example would be if the utility could not run because the server was unavailable.

The log files specific to the file being uploaded or downloaded will record the date/time when the utility is started and if it completed successfully. The log may also contain errors related to the file itself or permissions. For instance, if the file already exists when the upload tries to run, the log will show an error that the file already exists. If the authenticated user running the process did not have the proper permissions, those errors would be logged in this file.

Since the log files are appended to, they will become lengthy. To clear the log files, the user may simply delete the file and it will be created new the next time it runs.

Troubleshooting

Symptom

Message: The remote name could not be resolved: 'my_url'

Quick Fix

CartegraphURL setting not set on Cartegraph.RemoteDataTransfer.exe.config file.

 

Symptom

Message: Unable to connect to the Cartegraph server

Quick Fix

  • Make sure CartegraphAuthURL Setting is set to '/api/v1/authenticate'
  • Make sure Cartegraph OMS is up and running.

 

Symptom

Message: Cannot sign into Cartegraph. Verify the User Name and Password are correct.

Quick Fix

a. Make sure CartegraphUsername and CartegraphPassword is set on the Cartegraph.RemoteDataTransfer.exe.config file.

b. Make sure the user account is not inactive in Cartegraph OMS.

c. Make sure the user account is not deleted in Cartegraph OMS.

d. Make sure the password has not changed.

 

Symptom

Message: Unknown switch: '/something'

Quick Fix

Make sure the arguments are spelled correctly and start with '/'.

 

Symptom

Message: Request URL must start with base URL https://site.domain.com/Cartegraph

Quick Fix

Make sure the CartegraphURL is valid.

 

Symptom

Message: User does not have permission to upload attachments.

Message: User does not have permission to upload files to Import/Export.

Quick Fix

Verify the CartegraphUsername belongs to a Role that has Import/Export and Link/Attachment permission.

 

Symptom

Message: FileName: File already exist.

Quick Fix

Remove the file from the drop location.

 

Symptom

Message: Could not find a part of the path for file 'FileName.ext'.

Quick Fix

Verify the Project Home path is set correctly in Cartegraph OMS. Make sure you can upload an attachment for a recordset in OMS.

 

Symptom

Message: Unable to login to the Cartegraph server.

Quick Fix

Verify Cartegraph is up and running.

 

Symptom

Message: Unsupported file type

Quick Fix

Verify you are not trying to upload a file that has an extension that is unsupported. You can check the ExcludedAttachmentTypes system setting in Administration System Settings page.

  • Was this article helpful?