Backend CLI Tool

Available from Version: 9.7 #SR1
Label_For_Administrators.svg

The Backend CLI Tool is a command-line tool that is connected to the empower® Backend.

It can be used by empower® Administrators.

The Backend CLI Tool is used to fulfill the following tasks:

  • Bulk upload files such as presentations or pictures

  • Download a usage tracking report

The tool is installed via a separate .msi installer provided by empower.

To install the tool, the following prerequisites must be met:

  • .NET 8 Desktop Runtime (64-bit) is installed on the user's device.

  • Configuration file appsettings.json must be placed next to the tool's .msi installer during installation.

  • The device must be restarted after installation.

After the installation, the tool is placed under the following path:

%LocalAppData%\programs\empower\backendCli 

Important

The Backend CLI Tool can only be executed on Windows devices via the command-line.

The execution via PowerShell is not supported.

However, imported files are also available for empower® for macOS and usage data from macOS devices is also included in the usage report.

Note

You can also schedule the tasks to be executed automatically and periodically.

For further information regarding scheduling commands, see Schedule Commands.

Log in to the Tool

To log in to the Backend CLI Tool, use the following command:

backendCli.exe l 

The command opens a login window.

Log in to your user account. Depending on your configuration, this is either your empower® User or your Windows user.

If your Windows user is used, you might not need to sign in manually. Your user's ID will be used automatically.

In the command-line tool, you can see if your authentication has been successful.

Once you have logged in successfully, you can also execute tasks unattended in quiet mode.

To avoid login demands during automated tasks, always use the above command before scheduling any tasks.

Note

If you use your empower® User to log in, you need to grant the permission User.Read for Microsoft Graph for the application.

For further information regarding this permission, see Microsoft Graph permissions reference.

A dialog box opens.

Here, accept the permissions to be granted.

Depending on the guidelines in place, it may occur that only administrators can grant the required permissions. If this is the case in your company, the dialog box informs you that you need to contact an administrator.

Export Usage Report

The tool can be used to export a report of the usage of different library content.

This report reflects the data that is displayed for each library element on how often it has been used in the company.

To export the report as a .csv file, use the following command:

backendCli.exe r -o "[OUTPUT PATH]" 

The basic command consists of the following:

  • r – Indicates that a report should be created.

  • --output-folder [PATH] (-o) – Defines the output path to save the report.

    You can specify an individual path on your file system, e.g. C:\Users\[USER NAME]\Documents\empower Usage Report.

Optionally, you can make the command be executed in quiet mode to schedule the task.

To do so, add -q (--quiet) to the end of the command:

backendCli.exe r -o "[OUTPUT PATH]" -q 

Note

To run quiet mode, you must either run the command once in normal mode and log in during this task or have previously authenticated using the login command.

File Structure and Content

The report .csv file contains the following information per asset (Figure 1, “Usage Tracking Report”):

  • Name

  • Path

  • Type

  • Author

  • Editor

  • Last change date

  • Usage count

Figure 1. Usage Tracking Report

Usage Tracking Report

Bulk Upload Files

To upload multiple files such as pictures or presentations to empower® at once, use the following command:

backendCli.exe u -s "[SOURCE PATH]" -t "[TARGET PATH]" 

The basic command consists of the following:

  • u – Initiates the bulk upload of files.

  • --source [SOURCE PATH] (-s) – Defines the path containing the content to be imported.

  • --target [TARGET PATH] (-t) – Defines the folder to which the content should be imported.

    The folder can either be defined by a path or by its unique GUID in empower®. The GUID can be found in your empower® Database.

    For further information, see Valid Target Folders and File Types.

Optionally, you can make the command be executed in quiet mode to schedule the task.

To do so, add -q (--quiet) to the end of the command:

backendCli.exe u -s "[SOURCE PATH]" -t "[TARGET PATH]" -q 

Important

The source path must not end with a \ character.

The target path must not end with a > character.

Example

Source path

Correct: -s "C:\Users\[USER NAME]\Desktop\Pictures"

Incorrect: -s "C:\Users\[USER NAME]\Desktop\Pictures\"

Target path

Correct: -t "%CorporateDesignTemplates%>%Slides%"

Incorrect: -t "%CorporateDesignTemplates%>%Slides%>"

Valid Target Folders and File Types

The file paths to the folder on the machine and in the empower® Library must be specified in different ways.

For the paths that lead to files on your device, specify the path in the default path structure, separated by back slashes (\).

If you specify the folder in the empower® Library using a path instead of the GUID, use the following format:

%UserLibrary%>%MyContent%>[FOLDER NAME] 

The following table provides an overview of all valid folder paths and the respective supported file types that can be used within the command -t:

Folder Path

Section in Library

Supported File Types

%CompanyLibrary% 

Company Library

All supported file types in this table.

%CorporateDesignTemplates%>%CorporatePresentations% 

Corporate Presentations

.pptx, .pptm

%CorporateDesignTemplates%>%DocumentTemplates% 

Document Templates

.docx, .docm

%CorporateDesignTemplates%>%Icons% 

Icons

.jpg, .jpeg, .png, .gif, .svg, .tif

In addition, .tiff is only supported if the parameter -l is set to false.

%CorporateDesignTemplates%>%Images% 

OR

%CorporateDesignTemplates%>%Pictures% 

Pictures

.jpg, .jpeg, .png, .gif, .svg, .tif

In addition, .tiff is only supported if the parameter -l is set to false.

%CorporateDesignTemplates%>%MasterTemplates% 

Master Templates

.pptx, .pptm

%CorporateDesignTemplates%>%Slides% 

Slides

.pptx, .pptm

%UserLibrary%>%MyContent% 

OR

%UserLibrary% 

My Content

All supported file types in this table.

Important

The folder names of the data to be imported must not contain any periods.

Advanced Commands

If you want to specify more details for the bulk upload, you can add the following parameters to your command:

Command

Short Form

Description

Default

--includeSubfolders 

-i 

Defines if subfolders should be included.

This parameter can be set to true or false.

true 

--ignoreUnsupportedFiles 

-g 

Defines if unsupported files are skipped.

This parameter can be set to true or false.

If this parameter is disabled and there are unsupported files, the import is canceled and a message opens.

false 

--additionalInformationFile [PATH] 

-f 

Defines the relative path to an additional .csv file containing metadata to be uploaded with the files.

For further information, see Add Metadata to the Import.

-

--archiveSourceFolder [PATH] 

-r 

Defines the path to archive the import folder after successfully uploading the files.

The folder is then moved to the archive folder path and named after the time stamp.

false 

--updateNotification [MODE] 

-n 

Defines the update notification behavior.

This parameter can be set to force, update or disable.

This parameter does not affect Word files.

Update notifications are only supported for individual slides, presentations saved on a user's device, pictures in Word and pictures in PowerPoint uploaded via the parameter -l.

update 

--setTranslationsOutdated 

-x 

Defines if translations should be marked as outdated when files in a translation group are overwritten.

This parameter can be set to true or false.

This parameter depends on the parameter -n.

false 

--overwriteExistingFiles 

-o 

Defines if existing files in the empower® Library are overwritten. For this update to work, the imported file and the existing file must have the same name.

This parameter can be set to true or false.

If this parameter is disabled, existing files are skipped.

true 

--useIncrementalUpload 

-m 

Defines if only files are updated that have been changed since the last import.

This parameter can be set to true or false.

true 

--useLegacySlidesImageFormat 

-l 

Defines if the legacy picture format for empower® for PowerPoint is used.

This parameter can be set to true or false.

If this parameter is enabled, the picture files will only be imported to empower® for PowerPoint.

If this parameter is disabled, the picture files are uploaded in a global format which is compatible with empower® for PowerPoint, Word, Excel and Outlook.

false 

Important

If pictures are imported in the global file format which works for library content in all Office applications, updates do not work for empower® for PowerPoint. In addition, there is no version history for those files.

Therefore, the files are uploaded but the users do not receive update notifications.

For pictures in Word uploaded in the global file format, however, users do still receive update notifications.

Add Metadata to the Import

If you want to add metadata to your imported files, e.g. tags, you can create a separate .csv file containing this information.

During the import, the relative path to this file must be specified in the command.

Place the file in the import source folder or one of its subfolders.

Then, specify the relative path based on the source folder.

The content of the file should include the following, in the same order:

  • Relative path including file extension

  • Name (excluding file extension)

    • Defines a new file name to be stored in the empower® Library

    • If the name is not specified, the original file name from the import folder is used.

  • Tags to be displayed in the empower® Library

    • separated by semicolons

    • Put in double quotation marks (" ")

  • Single slide indicator

    • use x to define that only the first slide of a presentation should be imported.

    • If empty, the entire presentation is imported

The following excerpt provides an example for the structure of the .csv file:

 
Picture File 1.png;New Picture Name;"tag1;tag2;tag3";
Images\Picture File 2.png;;"tag4;tag5;tag6";
Slides\PowerPoint File 1.pptx;New Slide Name;"tag7;tag8";x
Presentations\PowerPoint File 2;;"tag9";

Note

If one of the specifications remains empty, e.g. if you do not want to specify a new name for the file, leave this space empty.

If so, there are two semicolons right next to each other (see line 2 and 4 in the sample structure).

Note

Not all files from the import folder need to be included in the .csv file.

Log Files

The upload process and potential errors are logged in a log file as well as in the command-line tool.

The log file is stored under the following path:

%LocalAppData%\empower\Logs\backendCli 

In the command-line tool, the errors are only logged if it is used in normal mode. In quiet mode, errors are only logged in the log file.

Was this article helpful?

/

Comments

0 comments

Article is closed for comments.