Introduction

The Izenda Copy Console Tool will allow you to copy templates, reports and dashboards from one Izenda Configuration database to another. If you need to copy reports within the same configuration database (eg. copying a report from one tenant to another) you can use the Copy Management Tool.

Understanding the Security of the Copy Console

Understanding The Copy Console XML

Options for the Copy Console are specified in an XML and provided to the Copy Console at runtime. An example of this XML can be found in the “Usage” section below. The following is an overview of the configurable options in your XML.

• Authentication: The Copy Console must be able to log in to Izenda in order to create a valid access token.

  • For standalone environments, you will simply need to provide the Izenda API URL along with valid credentials for your source and destinations.
  • In integrated modes, the authentication endpoint will be specified in the appAuthUrl of the Authentication object. A sample C# implementation can be found in the Using the Copy Console for Integrated Modes section below.

• Specifying a Tenant:Tenants are specified directly in your CopyConfig.xml by their ID found within the UI. If the Tenant ID value is left blank, it is assumed that you are copying to the System “tenant”

  

• Specifying the overwriteIfExists Flag: When a report is copied from one environment to another, a Source ID is cataloged in the destination. This control can be set at the tenant level within your configuraton file.

  <tenant id=”My Tenant ID” overwriteIfAlreadyExist=”yes”>

  • If flag is true: If the Source ID in the database matches the Source ID of the prospective copy and the report names match, the existing version of the report is overwritten.
  • If flag is false: If the Source ID in the database matches the Source ID of the prospective copy and the report names match, the existing version of the report is not overwritten.
  • At this time, there is not a setting to “make a copy” but not overwrite if the SourceIDs match and the names match (e.g. If “Report” exists, “Report(1)” is created).

• Specifying Database Mappings: In order to copy reports from one environment to another, a datasource must exist within the Destination that maps. Database mapping can be accomplished by specifying the source and destination’s database names.

  • When specifying your database mapping, you will need to obtain the database name and schema for both the source and destination. Both values can be found directly in the platform.
  • Database Objects used within your report must exist in both the source and destination. Database objects are not “mappable.” For instance, if a report is built with the “Orders” table in the Source, it cannot be mapped to an “Orders” view in the Destination. Similarly, if a report is build with the “Orders” table in the Source, it cannot be mapped to a “MyOrdersTable” in the Destination.

  

• Specifying Reports, Templates and Dashboards: These elements will be found in their respective XML tags within your CopyConfig.xml.

  • To reference a particular Report Object in your XML, you will specify its ID with its corresponding object type

  • Report Object IDs can be found within the URL when navigating to it in your web browser.

    

  • Report/template IDs can also be found within the IzendaReport table of your Izenda Configuration Database.

  • Dashboard IDs can also be found within the IzendaDashboard table of your Izenda Configuration Database.

Usage

1. Download a copy of the CopyConsoleTool.zip that corresponds to your version of Izenda from the Upgrade tab in the Izenda Customer Portal.

2. Download SampleConfig.xml from https://izenda.com/utilities/SampleConfig.xml

3. Unzip this application to the location you select.

4. Edit the SampleConfig.xml using the following as a template:

   • The Source Block tells the application where you are copying from as below:

     <source><!-- Specify the api credentials and the url of the source api--><credentialsuserName="Admin"password="Admin"apiUrl="http://localhost:2525/api"/><!—Tenant id is not a GUID, but rather the 'Tenant ID' field from the UI. If Tenant ID is BLANK your source location is System Level--><tenantid=""></tenant><!-- Specify the reports to copy based on the report id--><reports><reportid="4FA0D1D6-C4B5-435E-99D3-8B059724BE7C"/><reportid="41212145-C4B5-435E-99D3-8B059724BHC3"/></reports><!-- Specify the templates to copy using the template id --><templates><!--  <template id="51D71299-FCD0-402E-9DE0-AD428D26FAAA"/> --></templates><!-- Specify the dashboards to copy using the dashboard id--><dashboards><!-- <dashboard id="B68574CC-89EC-462F-9ED8-DF2F12FACC58"/>  --></dashboards></source>

   • Now you can configure the destination(s).

     Each destination can have a name, this will allow you to run one or all destinations from the command line (the destination name can be specified using the /d: command and the name).

     The destination block can be configured as below:

     <!-- Specify the destination(s)--><destinations><!-- Destination 1, These destinations can be run one at a time or all at once based on the name given for each destination by using the d:/parameter in the command line--><destinationname="UAT"><!-- Specify the api credentials --><credentialsuserName="Admin"password="Admin"apiUrl="http://10.100.5.86:80/api"/><!-- Specify the tenant(s)--><tenants><!-- id is not a GUID, but rather the 'Tenant ID' field from the UI. If Tenant ID is BLANK this is System Level. IF you would like to overwrite anything at the destination set overwrite to “yes” if not set to “no”--><tenantid=""overwriteIfAlreadyExist="yes"><!-- Specify the database mappings --><databaseMappings><!-- The database name is the name given to to the connection string in the UI of the application. This name is visible in the connection string page of the Izenda Application UI this is not the actual name of the database on your server. You must add the name and the schema for both the source and the destination --><databaseMappingsourceDatabaseName="northwind"sourceSchema="dbo"destinationDatabaseName="northwind"destinationSchema="dbo"/><databaseMappingsourceDatabaseName="northwind.100"sourceSchema="northwind"destinationDatabaseName="northwind"destinationSchema="northwind"/></databaseMappings><!-- Specify the role mappings, this is not required but if you need to map a role like IT from system to IT Department at the tenant location you can do so here. This is not required. If the role does not exist at the destination is will not be copied.--><roleMappings><!-- <roleMapping sourceRole="Accounting" destinationRole="Accounting"/> --><!-- <roleMapping sourceRole="IT" destinationRole="IT Department"/> --></roleMappings></tenant></tenants></destination><!-- Destination 2, These destinations can be run one at a time or all at once based on the parameters used in the command line--><destinationname="DEV"><!-- Specify the api credentials --><credentialsuserName="Admin"password="Admin"apiUrl="http://10.100.5.87:80/api"/><!-- Specify the tenant(s)--><tenants><!-- id is not a guid, but rather the 'Tenant ID' field from the UI. If Tenant ID is BLANK this is System Level--><tenantid="Tenant01"overwriteIfAlreadyExist="yes"><!-- Specify the database mappings --><databaseMappings><!-- The database name is the name given to to the connection string in the UI of the applicaiotn --><databaseMappingsourceDatabaseName="southwind"sourceSchema="dbo2"destinationDatabaseName="northwind"destinationSchema="dbo2"/><databaseMappingsourceDatabaseName="northwind"sourceSchema="northwind"destinationDatabaseName="northwind"destinationSchema="northwind"/></databaseMappings><!-- Specify the role mappings, this is not required but if you need to map a role ex. IT from system to IT Department at the tenant location input here--><roleMappings><!-- <roleMapping sourceRole="Accounting" destinationRole="Accounting"/> --><!-- <roleMapping sourceRole="IT" destinationRole="IT Department"/> --></roleMappings></tenant></tenants></destination></destinations>

5. Once you have configured the xml file you can begin to copy.

   You will need to run this from a command window. Navigate to the location of the exe where you unzipped it above. You will need to provide the path to the xml file configured above and the parameter for the destination if used. If this parameter is not used, all destinations will be run.

   Command Line example to run:

   C:\CopyConsoleV1\CopyConsoleTool>IzendaCopyConsoleApp.exe SampleConfig.xml /d:UAT
   							

   To view usage at the command line:

   C:\CopyConsoleV1\CopyConsoleTool>IzendaCopyConsoleApp.exe /?
   								Usage: IzendaCopyConsoleApp.exe <path to mapping file> [/d:<destination name>]
   							

   Options:

   /d:destinationname     (Optional) Specify the destination name. If this switch is omitted, all destinations will be copied.
   							

Using the Copy Console for Integrated Modes

In order for the copy console to function properly, it must be able to login to the source and destination sites and retrieve an access token that will be used throught the copy process. By default, the copy console will attempt to authenticate against the “api/user/login” endpoint for each site specified in the copy console configuration file.

publicActionResultCustomAuth(stringusername,stringpassword){OperationResultauthResult;varserializerSettings=newJsonSerializerSettings{ContractResolver=newCamelCasePropertyNamesContractResolver()};varjsonResult="";//validate login (more complex logic can be added here)#warning CAUTION!! Update this method to use your authentication scheme or remove it entirely if the copy console will not be used.if(username=="IzendaAdmin@system.com"&&password=="Izenda@123"){varuser=newUserInfo{UserName=username,TenantUniqueName="System"};vartoken=IzendaTokenAuthorization.GetToken(user);varaccessToken=newIzendaFramework.AccessToken{CultureName="en-US",Tenant=null,IsExpired=false,NotifyDuringDay=null,DateFormat="DD/MM/YYYY",Token=token};authResult=newOperationResult{Success=true,Messages=null,Data=accessToken};jsonResult=JsonConvert.SerializeObject(authResult,serializerSettings);returnContent(jsonResult,"application/json");}authResult=newOperationResult{Success=false,Messages=null,Data=null};jsonResult=JsonConvert.SerializeObject(authResult,serializerSettings);returnContent(jsonResult,"application/json");}

{"success":true,"messages":null,"data":{"token":"Tm90aGluZyB0byBzZWUgaGVyZSwgbW92ZSBhbG9uZy4=","tenant":null,"cultureName":"en-US","dateFormat":"DD/MM/YYYY","systemAdmin":false,"isExpired":false,"notifyDuringDay":null}}