Difference between revisions of "Upgrade Guide v2.5"

From ADF Docs
Jump to: navigation, search
(→‎Enable the CSRF Safe Mode for local ajaxProxy requests)
(→‎Update Site Level Override Components)
 
(26 intermediate revisions by the same user not shown)
Line 2: Line 2:
 
Follow the guide below if you are upgrading to ADF v2.5.
 
Follow the guide below if you are upgrading to ADF v2.5.
  
−
  '''IMPORTANT:''' ADF 2.5 can only be used with CommonSpot 10.6.1 or 10.5.2 or above.
+
  '''IMPORTANT:''' ADF 2.5+ requires CommonSpot 10.6.1 or 10.5.2 or above.
  
−
Before upgrading, please review the [http://community.paperthin.com/projects/ADF/docs/release-notes/Release-Notes-v2-5-0.cfm v2.5 Release Notes]
+
Before upgrading, please review the [http://community.paperthin.com/projects/ADF/docs/release-notes/Release-Notes-v2-5.cfm v2.5 Release Notes]
  
 
If you are upgrading from a version earlier than ADF v2.5, then please follow the guides for previous ADF versions:
 
If you are upgrading from a version earlier than ADF v2.5, then please follow the guides for previous ADF versions:
Line 45: Line 45:
 
## 2.5.0
 
## 2.5.0
 
# Upgrade was successful and you are running the ADF v2.5.
 
# Upgrade was successful and you are running the ADF v2.5.
−
 
−
 
  
 
== Post-Upgrade Steps ==
 
== Post-Upgrade Steps ==
  
−
=== Enable the CSRF Safe Mode for local ajaxProxy requests ===
+
=== Update Site Level Override Components ===
−
ADF 2.5 has the new security enhancement, "ajaxProxy CSRF Safe Mode" disabled by default. This is to allow developers an opportunity to update their ADF and ADF App ajaxProy related customizations, before enabling the CSRF attack prevention validation.
 
  
−
If your site is only using out of the box ADF and ADF Applications then you should enable the "ajaxProxy CSRF Safe Mode" immediately after upgrade.
+
* Any site level override ADF Lib components located in the "_cs_apps/lib/" folder will need to be renamed and the component "extends" updated to point to the latest version of the matching ADF Lib components.
  
−
In your '''ADF.cfc''' in the /_cs_apps/ folder in your site root, add the following line:
+
Example: "'''_cs_apps/lib/scripts_1_1.cfc'''" needs to become "'''scripts_2_0.cfc'''" and the extends value in the component tag will need to point to "'''ADF.lib.scripts.scripts_2_0'''"
−
enableADFcsrfSafeMode(true);
 
  
−
For a new ADF installs, update the line enableADFcsrfSafeMode(false); found in your site's /_cs_apps/ADF.cfc file, from "false" to "true" (see above).
+
* Also make sure all CFPROPERTY "injectedBean" type="dependency" tags at the top of any other site level override ADF Lib components files are also updated to the latest versions of the ADF Lib components.
  
−
If your site has custom code which uses the ADF's ajaxProxy for local requests before you can enable "ajaxProxy CSRF Safe Mode", using the steps above, you will need to add the CSRF_Token parameter and the method call to get the CSRF_token value to your ajaxProxy calls. Once the "ajaxProxy CSRF Safe Mode" is enabled, the CSRF token key/value pair is required to be passed along with the local request as either a Data or URL parameter, otherwise your ajaxProxy requests will not validate and fail.
+
Example: <cfproperty name="data" injectedBean="'''data_1_2'''" type="dependency"> should be updated to be <cfproperty name="data" injectedBean="'''data_2_0'''" type="dependency">
−
 
 
−
CSRF_Token as a Data parameter (using a jQuery.post):
 
−
<source>
 
−
jQuery.post("#application.ADF.ajaxProxy#",
 
−
{
 
−
  bean: 'dataService',
 
−
  method: 'getData',
 
−
  CSRF_Token: '#application.ADF.csSecurity.getCSRF_Token()#'
 
−
}
 
−
</source>
 
  
 +
=== Update Custom App Lib Component References ===
 +
* Update any ADF Lib component references in your custom ADF Apps to the latest versions of the matching ADF 2.0 Lib components in the App's appBeanConfig.cfm file (in the root of the App directory).
  
−
CSRF_Token as a URL parameter (using a jQuery.get):
+
Example: "addConstructorDependency(appBeanName, "'''scripts_1_2'''", "scripts"); " needs to become "addConstructorDependency(appBeanName, "'''scripts_2_0'''", "scripts");"
−
<source>
 
−
jQuery.get("#application.ADF.ajaxProxy#?bean=dataService&method=getData&CSRF_Token=#application.ADF.csSecurity.getCSRF_Token()#")
 
−
</source>
 
  
 
=== Register ADF Scripts as CommonSpot Resources ===
 
=== Register ADF Scripts as CommonSpot Resources ===
  
−
# Register the ADF Script Resources with CommonSpot (for ADF 2.0 and above only!)
+
* Register the ADF Script Resources with CommonSpot (for ADF 2.0 and above only!)
−
## Run the [[Register All Scripts|Register ALL Scripts]] tool.
+
** Run the [[Register All Scripts|Register ALL Scripts]] tool.
  
−
  '''IMPORTANT:''' The ADF thirdParty scripts libraries will not function when using ADF.scripts_2_0 loadScripts calls unless
+
  '''IMPORTANT:''' The ADF thirdParty scripts libraries will not function when using ADF.scripts_2_0 loadScripts calls unless they are registered as Resources in CommonSpot 10.x.  
−
they are registered as Resources in CommonSpot 10.x.  
 
  
 
<!--
 
<!--
Line 105: Line 89:
 
For more information regarding the registration of ADF 2.0 ThirdParty Scripts as Resources in CommonSpot 10, please refer to the README information in the "/lib/scripts/scripts_2_0_READ_ME.txt" file.
 
For more information regarding the registration of ADF 2.0 ThirdParty Scripts as Resources in CommonSpot 10, please refer to the README information in the "/lib/scripts/scripts_2_0_READ_ME.txt" file.
 
-->
 
-->
 +
=== Enable the CSRF Safe Mode for local ajaxProxy requests ===
  
−
=== Update Site Level Override Components ===
+
* Once your site is ready Enable [[ADF AjaxProxy CSRF Safe Mode]] (for ADF 2.5 and above only!)
−
 
 
−
* Any site level override ADF Lib components located in the "_cs_apps/lib/" folder will need to be renamed and the component "extends" updated to point to the latest version of the matching ADF Lib components.
 
−
 
 
−
Example: "_cs_apps/lib/scripts_1_1.cfc" needs to become "scripts_2_0.cfc" and the extends value in the component tag
 
−
will need to point to "ADF.lib.scripts.scripts_2_0"
 
−
 
 
−
=== Update Custom App Lib Component References ===
 
−
* Update any ADF Lib component references in your custom ADF Apps to the latest versions of the matching ADF 2.0 Lib components in the App's appBeanConfig.cfm file (in the root of the App directory).
 
  
−
  Example: "addConstructorDependency(appBeanName, "scripts_1_2", "scripts"); " needs to become
+
  '''WARNING''': Enabling the "ADF CSRF Safe Mode" without installing ADF 2.5 compatible Apps or without updating all custom ajaxProxy local requests will greatly limit functionality!
−
"addConstructorDependency(appBeanName, "scripts_2_0", "scripts");"
 
  
 
== Related Guides ==
 
== Related Guides ==

Latest revision as of 18:31, 25 January 2022

Current Version

Follow the guide below if you are upgrading to ADF v2.5. 

IMPORTANT: ADF 2.5+ requires CommonSpot 10.6.1 or 10.5.2 or above.

Before upgrading, please review the v2.5 Release Notes

If you are upgrading from a version earlier than ADF v2.5, then please follow the guides for previous ADF versions:

Previous ADF Upgrade Guides

Upgrade

Follow the steps below to upgrade the ADF directory:

  1. Download the ADF v2.5 from the Community site project page.
  2. On your server, rename the "/ADF/" directory to "/ADF-2.4.1/".
  3. Create a new "/ADF/" directory. Setup any necessary security or permissions for the new "/ADF/" directory.
  4. Export the download ADF zip folder into the "/ADF/" directory.
  5. Copy the contents of the "/ADF-2.4.1/apps/" directory into the "/ADF/apps/" directory.
  6. Reset the ADF through the web browser with the following URL parameter:
    1.  ?resetADF=1

Note: If you have security permissions on the "/ADF/" directory make sure to set them up because the folder was renamed and then created new.

Validate Upgrade

There are 2 methods to validate the ADF upgrade.

ADF Reset

  1. Reset the ADF through the web browser with the following URL parameter:
    1.  ?resetADF=1
  2. The reset command will add text to the top line of the page. If you see the following text with the date/time stamp:
    1. ADF v2.5 has been reset successfully!
  3. Upgrade was successful and you are running the ADF v2.5.

ADF Version Output

  1. In the browser, add the following URL parameter:
    1.  ?ADFDumpVar=application.ADF.version
  2. This command with output the ADF version at the top of the page. If you see the following text:
    1. 2.5.0
  3. Upgrade was successful and you are running the ADF v2.5.

Post-Upgrade Steps

Update Site Level Override Components

  • Any site level override ADF Lib components located in the "_cs_apps/lib/" folder will need to be renamed and the component "extends" updated to point to the latest version of the matching ADF Lib components.
Example: "_cs_apps/lib/scripts_1_1.cfc" needs to become "scripts_2_0.cfc" and the extends value in the component tag will need to point to "ADF.lib.scripts.scripts_2_0"
  • Also make sure all CFPROPERTY "injectedBean" type="dependency" tags at the top of any other site level override ADF Lib components files are also updated to the latest versions of the ADF Lib components.
Example: <cfproperty name="data" injectedBean="data_1_2" type="dependency"> should be updated to be <cfproperty name="data" injectedBean="data_2_0" type="dependency">

Update Custom App Lib Component References

  • Update any ADF Lib component references in your custom ADF Apps to the latest versions of the matching ADF 2.0 Lib components in the App's appBeanConfig.cfm file (in the root of the App directory).
Example: "addConstructorDependency(appBeanName, "scripts_1_2", "scripts"); " needs to become "addConstructorDependency(appBeanName, "scripts_2_0", "scripts");"

Register ADF Scripts as CommonSpot Resources

  • Register the ADF Script Resources with CommonSpot (for ADF 2.0 and above only!) 
IMPORTANT: The ADF thirdParty scripts libraries will not function when using ADF.scripts_2_0 loadScripts calls unless they are registered as Resources in CommonSpot 10.x.

Enable the CSRF Safe Mode for local ajaxProxy requests

WARNING: Enabling the "ADF CSRF Safe Mode" without installing ADF 2.5 compatible Apps or without updating all custom ajaxProxy local requests will greatly limit functionality!

Related Guides

CommonSpot Registered Resources

Retrieved from "http://community.paperthin.com/adf-docs/index.php?title=Upgrade_Guide_v2.5&oldid=7842"