CurrencyField

• Available Since API Version – 2.4\

The CurrencyField type is used to represent currency fields in Octopus API, including numeric user-defined fields with the "Display Currency Symbol" option selected. CurrencyField objects contain the following properties:

• Value - A numeric value containing the value of the field. May be cleared by setting a null value. Has a "decimalplaces" property indicating the number of decimal places that are retained.\

• CurrencyCode - A string value containing the currency symbol or code for the field. The CurrencyCode is read-only.\

• DisplayValue - A string value containing the currency value formatted for display. The DisplayValue is read-only.\

Basic Read Request

The highlighted portion of the following example illustrates the syntax for a request for the default value of a CurrencyField in a Read method call.

Request

{
   "Token":"{{Token}}",
   "AbEntry":{
      "Criteria":{
         "SearchQuery":{
            "CompanyName":{
               "$EQ":"Delta Bike Company"
            }
         }
      },
      "Scope":{
         "Fields":{
            "Key":1,
            "Udf/$NAME(Forecast Revenue)":1
         }
      }
   }
}

Response

{
   "Code":0,
   "AbEntry":{
      "Data":[
         {
            "Key":"Q29tcGFueQlERU1PXzRDCTA=",
            "Udf/$NAME(Forecast Revenue)":1234.0
         }
      ]
   }
}

Detailed Read Request

The highlighted portion of the following example illustrates the syntax for a request for all properties of a CurrencyField in a Read method call.

Request

{
   "Token":"{{Token}}",
   "AbEntry":{
      "Criteria":{
         "SearchQuery":{
            "CompanyName":{
               "$EQ":"Delta Bike Company"
            }
         }
      },
      "Scope":{
         "Fields":{
            "Key":1,
            "Udf/$NAME(Forecast Revenue)":{
               "Value":1,
               "DisplayValue":1,
               "CurrencyCode":1
            }
         }
      }
   }
}

Response

{
   "Code":0,
   "AbEntry":{
      "Data":[
         {
            "Key":"Q29tcGFueQlERU1PXzRDCTA=",
            "Udf/$NAME(Forecast Revenue)":{
               "Value":1234.0,
               "DisplayValue":"CAD1,234.00",
               "CurrencyCode":"CAD"
            }
         }
      ]
   }
}

Basic Create/Update Request

The following example illustrates the syntax for including a CurrencyField in a Create or Update method call.

Request

{
   "Token":"{{Token}}",
   "AbEntry":{
      "Data":{
         "Key":"{{AbEntryKey}}",
         "Udf/$NAME(Forecast Revenue)":1234.56
      }
   }
}

Response

{
   "Code":0,
   "AbEntry":{
      "Data":{
         "Key":"Q29tcGFueQkxOTA5MTcyNTA5MTgxNTE3MDA0MzBDCTA=",
         "Udf/$NAME(Forecast Revenue)":1234.56
      }
   }
}

Detailed Create/Update Request

The following example illustrates the syntax for including a CurrencyField in a Create or Update method call.

Request

{
   "Token":"{{Token}}",
   "AbEntry":{
      "Data":{
         "Key":"{{AbEntryKey}}",
         "Udf/$NAME(Forecast Revenue)":{
            "Value":1234,
            "DisplayValue":"CAD1234.00",
            "CurrencyCode":"CAD"
         }
      }
   }
}

Response

{
   "Code":0,
   "AbEntry":{
      "Data":{
         "Key":"Q29tcGFueQkxOTA5MTcyNTA5MTgxNTE3MDA0MzBDCTA=",
         "Udf/$NAME(Forecast Revenue)":{
            "Value":1234.0,
            "DisplayValue":"CAD1,234.00",
            "CurrencyCode":"CAD"
         }
      }
   }
}

Common Pitfalls

The following are some examples that illustrate incorrect syntax for including CurrencyField in requests.

Invalid Create/Update Request - String Value

The default Value property of a CurrencyField is a floating-point numeric value. String values are not valid, even if the Value in question is a string representation of an integer or floating-point number.

In the Update example below, the call will fail because the Value is passed as a string.

{
   "Token":"{{Token}}",
   "AbEntry":{
      "Data":{
         "Key":"{{AbEntryKey}}",
         "Udf/$NAME(Forecast Revenue)":"1234.56"
      }
   }
}

Invalid Create/Update Request - Missing Value

When setting the value for a CurrencyField, you must use the Value of the value that you want to set. Passing only the DisplayValue will result in the value not being set correctly. In the Update example below, the call will fail because the Value is missing from the request.

{
   "Token":"{{Token}}",
   "AbEntry":{
      "Data":{
         "Key":"{{AbEntryKey}}",
         "Udf/$NAME(Forecast Revenue)":{
            "DisplayValue":"CAD1234.00"
         }
      }
   }
}

Invalid Create/Update Request - Mismatched Value, DisplayValue, and CurrencyCode

When setting the value for a CurrencyField in a Create or Update request, only the Value property of the field is observed. In the example below, a DisplayValue is passed that does not match the supplied Value, and a CurrencyCode is passed that does not match the corporate currency configured for this Address Book. The request will succeed because the "Value" property is supplied. However it may have unintended effects, as the value of the field will be set based on the supplied Value property (1234.56), and both the DisplayValue and CurrencyCode properties will be ignored.

{
   "Token":"{{Token}}",
   "AbEntry":{
      "Data":{
         "Key":"{{AbEntryKey}}",
         "Udf/$NAME(Forecast Revenue)":{
            "Value":1234.56,
            "DisplayValue":"USD4321.00",
            "CurrencyCode":"GBP"
         }
      }
   }
}