Lookups

Lookup Keys allow the DreamFactory administrator to store any number of "key value" pairs that can be attached to an app, a user, a role, or to the global system configuration of the instance itself. The key names can be used in a variety of DreamFactory interfaces by any API client, and the key values are automatically substituted on the server. Any Lookup Key can be marked as private, which causes the key's value to be securely stored on the server-side and not retrievable by the client, even with admin credentials.

System Keys

DreamFactory provides some "automatic" system-created Lookup Keys that are always available. These keys include information from the current user session, user information, role information, and the current instance name and versioning are also provided. These automatic Lookup Keys simplify many use case scenarios. For example, connecting a user by email address in an external database is easy. There is no need to create an email Lookup Key for each user.

• session.token
• user.id
• user.email
• user.display_name
• user.first_name
• user.last_name
• role.id
• role.name
• app.id
• app.name
• app.api_key
• df.name
• df.api_version
• df.version
• df.host_url
• df.confirm_invite_url
• df.confirm_register_url
• df.confirm_reset_url

Provisioning

Lookup keys and values can be provisioned via the Admin console on the App, Role, and User tabs, as well as the Config tab in the Lookups menu option. There's a hierarchy to lookup keys, starting from global system keys, then to app keys, then role keys, and finally, user keys. The system will use the most specific one provisioned for the value in play. This allows you to create a system of default settings and, if needed, overrides for special cases. Consider the case of using lookup keys for configuring credentials on a database service. Some basic read-only credentials may be set as global system keys. Another set of credentials with read and write access may be provisioned on a particular role. And more admin-like credentials can be provisioned for a single user of that role. As long as the keys are named the same, the hierarchy allows for overriding of how the database is accessed without creating a different service for each scenario.

In Global Config

For those not in Role A or Role B these credentials will be used. These users have no lookup key at the user or role level.

In Role Config

For those users in Role A or Role B these credentials will be used. Since these users have a lookup key at the role level, the one at the global level will never be used.

In User Config

There is a special user in Role A who requires admin level database permissions. You can add a user lookup key that will override the role lookup key only for that one user. All other users in Role A get the role level credentials.

Usage

Lookup keys can be used in several interfaces of the DreamFactory instance. Typically, lookup keys are designated by wrapping the key name in curly braces, i.e. {some_name}. Lookup keys can be used in the following interfaces.

• In service credentials and configuration fields - Private keys only! For example, the username and password fields required to hook up a SQL database.
• In Email Services & Templates in the subject line and message body - For example, using the user's name or instance name or URL.
• In Remote Web Services as parameters or headers - Private keys only!
• In Server-Side Filters in the Role Service Access provisioning.
• In posted data records or parameters in filters in SQL and NoSQL Database services.

One simple yet important use of Lookup Keys is to hide the master credentials required for integration with an external system. For example, if you are using Amazon S3 then you will have an Access Key and Secret Key provided by AWS. Both of these values could be saved as private Lookup Keys. Then you can use the key names in place of the actual credentials in the Admin Console. Later, if you wanted to connect to another Amazon service like Dynamo DB, you could just reuse the same key names. In this manner, your secret keys are encrypted and only used on the server-side for authentication with an external system. Private keys must be used for credentials and passwords and cannot be used elsewhere.

Here's how you would use the lookup keys for username and password on a database service. The system will replace {db_username} and {db_password} with the most specific lookup keys defined for the user making the API call.

Modifiers

As of the 2.4.0 release, wherever you use lookups, you can now add certain modifiers to them to do things like formatting, change case, etc. For example, if you wish to encode a lookup value so that you can safely use it in a URL link in an email template, you could use the following syntax...

   http://www.example.com/?parameter_name={urlencode(lookup_name)}

You can even daisy-chain the modifiers to get a desired output...

   http://www.example.com/?parameter_name={urlencode(base64_encode(lookup_name))}

Available Modifiers

The following are the default lookup modifiers currently supported. These can be found in the config/df.php file in the install directory under the allowed_modifiers attribute of the lookup section. Note: If you know PHP, you will probably see that some of these are placeholders for internal calls to the PHP supported functions, thus your overrides can use similar functions that take a single argument and return a single value.

• strtoupper - Return the lookup value as an uppercase string.
• strtolower - Return the lookup value as a lowercase string.
• ucfirst - Uppercase the first character of the lookup value.
• lcfirst - Lowercase the first character of the lookup value.
• ucwords - Uppercase the first character of each word in the lookup value.
• urlencode - URL-encodes the lookup value, http://php.net/manual/en/function.urlencode.php.
• urldecode - URL-decodes the lookup value, http://php.net/manual/en/function.urldecode.php.
• rawurlencode - URL-encodes lookup value according to RFC 3986, http://php.net/manual/en/function.rawurlencode.php.
• rawurldecode - URL-decodes lookup value according to RFC 3986, http://php.net/manual/en/function.rawurldecode.php.
• base64_encode - Encodes lookup value with MIME base64, http://php.net/manual/en/function.base64-encode.php
• base64_decode - Decodes lookup value encoded with MIME base64, http://php.net/manual/en/function.base64-decode.php.
• trim - Strips whitespace from the beginning and end of a lookup value

Don't see a modifier that you think would be useful, let us know via our support channels.

Overriding Available Modifiers

These defaults can be overridden in the .env file in the install directory, by adding a comma-delimited function list for the attribute DF_LOOKUP_MODIFIERS.

Note: Set this attribute to an empty value to disable this feature if desired.