salesforce / formula-engine

Extensible Formula Parser Engine with a Java, SQL, and Javascript execution engine.

formula-engine

An implementation of a reusable formula engine with javascript & sql generation along with Salesforce-approved syntax.

For the end-user documentation of the formula engine's functionality, please see the end-user facing documentation.

In order to implement this formula engine in your application, you need to

• Include grammaticus, formula-engine-api, and formula-engine-impl in your application.
• Look at FormulaEngineHooks, FormulaValidationHooks and implement the needed ones for your application during initialization.
• Think about your type system. You'll need a Class that represents the type along with a FormulaDataType implementation that's used manage type conversion and error handling. You'll need something like MockFormulaDataType in your application, but if you're only handling strings, it can be simple.
• Override the FormulaFactoryImpl, probably adding FieldReferenceCommandInfo and DynamicReference to the commands, along with whichever implementations of FormulaCommandInfo you need for your application.
• Have a grammaticus localizer for any exception handling. For the minimum work, copy the MockLocalizerContext included in the test code, set the LocalizerFactory at the start of your application. You may want to override FormulaValidationHooks.getLocalizer() to return the same localizer.
• Implement a FormulaTypeSpec implementation that returns a valid getDefaultProperties, probably as an Enum. If you want different type of formulas in your application, make it an Enum like in MockFormulaType. If you want javascript generated for mobile/offline use, you'll need to override that here.
• Create a FormulaContext that represents your data providers. Make sure your root context implements getProperty, setProperty, getFormulaReturnType, isFunctionSupported as they will be called in all circumstances. Extending BaseCompositeFormulaContext is probably easiest for your Root/Default formula context. Then addContextProvider for the various stuff you include
• The formula engine can parse hierarchies like Contact.Account.Name, but each formula context will get a chance to return the field at each point of the hierarchy, so you can override the results
• You can use different formula engines for compilation in FormulaEngine.getFactory().create(...) and then reuse that with different runtime contexts when you call getFormula().evaluate(...). This lets you reuse the FormulaInfo multiple times, as formula parsing is somewhat expensive. If you want to handle the type conversions yourself, call evaluateRaw, not evaluate on the formulas.
• If you're using javascript, you need to have a few functions installed in the context of the org, usually as $F. See FormulaJsTestUtils.getFunctionScript() for the examples. You'll also want to load the included decimal.js if you want high precision decimals client side, suitable for currencies.

issues

• We assume the DB is running in GMT mode for much of the date/time logic
• Upper/Lowercase in many DBs differs from java due to double s (ß) handling
• The engine hooks and list of commands are stored in global static state which makes coexistence with other DI frameworks like spring a problem.
• MySQL support assumes the database uses case insensitive collation (utf8_bin) to match other DBs. If you're DB is case sensitive, there will be discrepancies between the DB and the Java/Javascript evalution.
• Array and Map support doesn't translate to DB queries for DBs that support it
• Not all functions are supported in all DBs. Use a FunctionFilter, as level of support differs from throwing UnsupportedOperationException to minor differences in corner cases.

formula-engine's Issues

Using the generated com.force.formula.parser.gen.FormulaTokenTypes.java with mvn imported formula-engine

Hi,

what will the correct approach be to get FormulaTokenTypes in the codebase of a client project which uses formula-engine? Within the formula-engine itself it is possible to get FormulaTokenTypes by simply executing mvn package, which generates the enum. But when the formula-engine is a dependency to the client project the enum will be missing.

It is of course possible to simply generate the enum by building formula-engine in the particular version and then copying the generated class to the client project, but is there a better way to do that?

Kind Regards

TYPO in FormatCurrency

<param name="FORMATCURRENCY_DESCR">Format the given number as a current using the scale of the given currency code, with that code prepended.</param>
Want to confirm with you that current in the above label should actually be currency?

Cannot find class FormulaTokenTypes

Hello there, Good days.
First of all thanks for open sourcing this great product, i am sure it's a great contribution towards open source and the common development of dynamic programming.

I did a little weekend hackathon and managed to compile the project and run formulas, but i had to do the dirty trick of

mvn package -DskipTests

in order to build the jar artifacts.

The problem is that i am having problems compiling the impl project, because in the FormulaUtils class it's importing the class

import com.force.formula.parser.gen.FormulaTokenTypes;

but it cannot seem to find it.

I suspected maybe it's a generated class from antlr grammar but i attempted to run the command

mvn antlr:generate

but to no avail. I've run out of options and still trying to figure out whats happening, could you please help?

Thanks for the Attention.