Declared Constants define a value that is used in an eFORMz project, but can be changed without editing the project. They’re similar to constants defined in a header file in the C programming language. More information about how they are defined can be found here: Set Value from a Declared Constant

Web services are used for accessing shipping services (e.g. FedEx, UPS, etc.), for accessing marketplaces (e.g. Amazon, Wayfair, etc.), and for accessing other systems (e.g. warehouse management systems, ERP systems). When accessing a web service, there are typically several pieces of information that must be specified, such as:

• URL to call for the web service
• Credentials to ensure that the user is authorized.
  • User name and password
  • Authorization tokens

Also, these web services often have at least two environments, each with their own credentials:

• Test (sometimes called Dev or Sandbox)
• Production

The URL and credentials for these two environments can be stored as Declared Constants; following are some suggestions for setting up the configuration files for this purpose.

How to Define a Declared Constant

To define global configuration options for eFORMz, including Declared Constants, consult the following: Globally defined eFORMz configuration options

The preferred method is to place an eFORMz*.xml file in the settings folder. This file can contain the Declared Constants directly, or it can reference other files (which themselves can reference other files) that contain the actual Declared Constants.

Define Two Sets of Declared Constants

Create two files, one for test/dev/sandbox credentials, and the other for production credentials, named something like the following:

eFORMzProject_Sandbox.xml        eFORMzProject_Production.xml

These configuration files can contain the Declared Constants directly or they can reference other configuration files that contain them. For simplicity, let us assume that these files do not reference other files, but contain everything.

The same Declared Constants are defined in both files, but with values for Sandbox or Production, as appropriate. Place both files in the settings directory, then if you want to use the Sandbox credentials, add a “.bak” extension to the Production file:

eFORMzProject_Sandbox.xml    eFORMzProject_Production.xml.bak

This will prevent this file from being loaded, so the Sandbox credentials will be loaded for your projects to use. If you want to use Production credentials, add a “.bak” extension to the Sandbox and remove it from the Production file:

eFORMzProject_Sandbox.xml.bak     eFORMzProject_Production.xml

Now the Production credentials will be used. Appending a “.bak” to the configuration filename is just one method you can use to force it to not be loaded. Another way you could accomplish the same result is to create a directory under the settings directory and copy the configuration file you do not want to use to that directory, leaving only the configuration file you want to use in the settings directory.

Examples

Examples can help to clarify this method of separating production credentials from sandbox credentials. For both examples, we will define the following Declared Constants:

• AcmeAPI_WebServiceUrl
• AcmeAPI_TokenItem1
• AcmeAPI_TokenItem2

Example 1 – Self-Contained Configuration Files

For this example, we will define the Declared Constants directly in the configuration file in the settings directory. First, the sandbox file, eFORMzProject_Sandbox.xml:

<?xml version="1.0" encoding="utf-8"?>
 <eFORMzConfiguration>
   <Constant Name="AcmeAPI_WebServiceUrl">
     <![CDATA[https://sandbox.acme.com/web-services]]>
   </Constant>
   <Constant Name="AcmeAPI_TokenItem1">
     <![CDATA[SandboxTokenItem1HopefullyEncrypted]>
   </Constant>
   <Constant Name="AcmeAPI_TokenItem2">
     <![CDATA[SandboxTokenItem2HopefullyEncrypted]>
   </Constant>
 </eFORMzConfiguration>

Then, the production file, eFORMzProject_Production.xml:

<?xml version="1.0" encoding="utf-8"?>
 <eFORMzConfiguration>
   <Constant Name="AcmeAPI_WebServiceUrl">
     <![CDATA[https://production.acme.com/web-services]]>
   </Constant>
   <Constant Name="AcmeAPI_TokenItem1">
     <![CDATA[ProductionTokenItem1HopefullyEncrypted]>
   </Constant>
   <Constant Name="AcmeAPI_TokenItem2">
     <![CDATA[ProductionTokenItem2HopefullyEncrypted]>
   </Constant>
 </eFORMzConfiguration>

Note that the Declare Constant names are the same in both files, but the values are different. Whichever one of these files is loaded determines the values of the Declared Constants. Preventing eFORMz from loading the unwanted file (by adding a “.bak” extension or moving to another directory) will ensure that the Declared Constants have the correct values for the desired environment.

Example 2 – Nested Configuration Files

This example demonstrates another method of choosing which set of Declared Constants is loaded. Create a single configuration file in the settings directory that contains references to two other configuration files and comment out the unwanted file using the XML comment directive. Start the commented-out section by adding “!--” after the opening angle bracket of the XML node we want to comment out and add “--” before the closing angle bracket of the same XML node (leave out the double quotes in both cases). Here is an example of an XML node and the same XML node commented out:

<Node Name="SomeName">ValueOfNode</Node>
<!--Node Name="SomeName">ValueOfNode</Node-->

First, define the eFORMzProject.xml file in the settings directory:

<?xml version="1.0" encoding="utf-8"?>
 <eFORMzConfiguration>
   <File Name="projects/MyProject/eFORMzCfg_Sandbox.xml"></File>
   <File Name="projects/MyProject/eFORMzCfg_Production.xml"</File>
 </eFORMzConfiguration>

Then define the two files that are referenced above. First, the sandbox file, eFORMzProject_Sandbox.xml:

<?xml version="1.0" encoding="utf-8"?>
 <eFORMzConfiguration>
   <Constant Name="AcmeAPI_WebServiceUrl">
     <![CDATA[https://sandbox.acme.com/web-services]]>
   </Constant>
   <Constant Name="AcmeAPI_TokenItem1">
     <![CDATA[SandboxTokenItem1HopefullyEncrypted]>
   </Constant>
   <Constant Name="AcmeAPI_TokenItem2">
     <![CDATA[SandboxTokenItem2HopefullyEncrypted]>
   </Constant>
 </eFORMzConfiguration>

Then, the production file, eFORMzProject_Production.xml:

<?xml version="1.0" encoding="utf-8"?>
 <eFORMzConfiguration>
   <Constant Name="AcmeAPI_WebServiceUrl">
     <![CDATA[https://production.acme.com/web-services]]>
   </Constant>
   <Constant Name="AcmeAPI_TokenItem1">
     <![CDATA[ProductionTokenItem1HopefullyEncrypted]>
   </Constant>
   <Constant Name="AcmeAPI_TokenItem2">
     <![CDATA[ProductionTokenItem2HopefullyEncrypted]>
   </Constant>
 </eFORMzConfiguration>

Finally, decide which set of Declared Constants you want to load, and comment out the other file in the eFORMzProject.xml file in the settings directory. For example, if you want to load the sandbox settings, comment out the production line, like this:

<?xml version="1.0" encoding="utf-8"?>
 <eFORMzConfiguration>
   <File Name="projects/MyProject/eFORMzCfg_Sandbox.xml"></File>
   <!--File Name="projects/MyProject/eFORMzCfg_Production.xml"></File-->
 </eFORMzConfiguration>